1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter3.Setting up Netatalk</title><link rel="stylesheet" href="netatalk.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="Netatalk 2.0 Manual"><link rel="up" href="index.html" title="Netatalk 2.0 Manual"><link rel="previous" href="installation.html" title="Chapter2.Installation"><link rel="next" href="upgrade.html" title="Chapter4.Upgrading from a previous version of Netatalk"><link rel="stylesheet" type="text/css" charset="iso-8859-1" href="printer.css" media="print"><link rel="alternate stylesheet" type="text/css" charset="iso-8859-1" href="printer.css" title="Printer"><link rel="copyright" title="GNU General Public License" href="http://www.gnu.org/copyleft/gpl.html#SEC1"><link rel="author" title="The Netatalk Development Team" href="http://netatalk.sf.net"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter3.Setting up Netatalk</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="installation.html">Prev</a></td><th width="60%" align="center"></th><td width="20%" align="right"><a accesskey="n" href="upgrade.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="configuration"></a>Chapter3.Setting up Netatalk</h2></div></div><div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="configuration.html#id2836170">Appletalk</a></span></dt><dd><dl><dt><span class="sect2"><a href="configuration.html#id2836205">To use AppleTalk or not</a></span></dt><dt><span class="sect2"><a href="configuration.html#id2836304">No AppleTalk routing</a></span></dt><dt><span class="sect2"><a href="configuration.html#id2836512">atalkd acting as an AppleTalk router</a></span></dt></dl></dd><dt><span class="sect1"><a href="configuration.html#id2836984">File Services</a></span></dt><dd><dl><dt><span class="sect2"><a href="configuration.html#id2837047">Setting up the AFP file server</a></span></dt><dt><span class="sect2"><a href="configuration.html#CNID-backends">CNID backends</a></span></dt><dt><span class="sect2"><a href="configuration.html#charsets">Charsets/Unicode</a></span></dt><dt><span class="sect2"><a href="configuration.html#authentication">Authentication</a></span></dt></dl></dd><dt><span class="sect1"><a href="configuration.html#printing">Printing</a></span></dt><dd><dl><dt><span class="sect2"><a href="configuration.html#papserver">Setting up the PAP print server</a></span></dt><dt><span class="sect2"><a href="configuration.html#papclient">Using AppleTalk printers</a></span></dt></dl></dd><dt><span class="sect1"><a href="configuration.html#timeservices">Time Services</a></span></dt><dd><dl><dt><span class="sect2"><a href="configuration.html#timelord">Using Netatalk as a time server for Macintoshes</a></span></dt></dl></dd><dt><span class="sect1"><a href="configuration.html#id2900410">Starting and stopping Netatalk</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2836170"></a>Appletalk<a class="indexterm" name="id2836176"></a></h2></div></div><div></div></div><p>AppleTalk, the network protocol family founded by Apple, contains
different protocols for different uses (address resolution, address/name
mapping, service location, establishing connections, and the like)</p><p>A complete overview can be found inside the developer
documentation.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2836205"></a>To use AppleTalk or not</h3></div></div><div></div></div><p>You'll need the AppleTalk support built into netatalk in case you
want to provide printing services via PAP by <a href="papd.8.html"><span class="citerefentry"><span class="refentrytitle">papd</span>(8)</span></a> or file services via AppleTalk via <a href="afpd.8.html"><span class="citerefentry"><span class="refentrytitle">afpd</span>(8)</span></a> for older AFP clients not capable of using AFP over
TCP. You'll need it also, if you want to use the deprecated
AppleTalk-based timeserver <a href="timelord.8.html"><span class="citerefentry"><span class="refentrytitle">timelord</span>(8)</span></a> for older Mac clients.</p><p>But even if you don't need PAP or AFP over AppleTalk, you might
consider using AppleTalk for service propagation/location, having the
ease of use for your network clients in mind. The Apple engineers
implemented a way to easily locate an AFP server via AppleTalk but
establishing the AFP connection itself via AFP over TCP (see the
developer documentation for details on this cool feature, too).</p><p>To use the different base AppleTalk protocols with netatalk, one
has to use <a href="atalkd.8.html"><span class="citerefentry"><span class="refentrytitle">atalkd</span>(8)</span></a>. It can also be used as an AppleTalk router to connect
different independent network segments to each other.</p><p>To use AppleTalk/atalkd, your system has to have kernel support
for AppleTalk. On some systems supported by netatalk, this isn't
currently true (notably True64 Unix) so you can use only netatalk
services that do not rely on AppleTalk (which means "AFP over TCP" and
requires the -noddp switch in afpd.conf).</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2836304"></a>No AppleTalk routing</h3></div></div><div></div></div><p>This is the most simple form, you can use AppleTalk with netatalk.
In case, you have only one network interface up and running, you haven't
to deal with atalkd's config at all: atalkd will use AppleTalk's
self-configuration features to get an AppleTalk address and to register
itself in the network automagically.</p><p>In case, you have more than one active network interface, you have
to make a decision:</p><div class="itemizedlist"><ul type="disc"><li><p>Using only one interface: Just add the interface name (en1,
le0, eth2, ... for example) to atalkd.conf on a single line. Do only
list <span class="emphasis"><em>one</em></span> interface here.</p><div class="example"><a name="id2836345"></a><p class="title"><b>Example3.1.atalkd.conf containing one entry</b></p><pre class="programlisting">eth0</pre><p>Appletalk networking
should be enabled on eth0 interface. All the necessary
configuration will be fetched from the network</p></div><p>At startup time, atalkd will add the real settings (address
and network and eventually a zone) to atalkd.conf on its own</p><div class="example"><a name="id2836375"></a><p class="title"><b>Example3.2.atalkd.conf containing one entry after atalkd
started</b></p><pre class="programlisting">eth0 -phase 2 -net 0-65534 -addr 65280.166</pre><p>
atalkd filled in the AppleTalk settings that apply to this network
segment. A netrange of 0-65534 indicates that there is no
AppleTalk router present, so atalkd will fetch an address that
matches the following criteria: netrange from inside the so called
"startup range" 65280-65533 and a node address between 142 and
255.</p></div></li><li><p>When using several interfaces you have to add them line by
line following the "-dontroute" switch in atalkd.conf.</p><div class="example"><a name="id2836411"></a><p class="title"><b>Example3.3.atalkd.conf containing several entries with the -dontroute
option</b></p><pre class="programlisting">eth0 -dontroute
eth1 -dontroute
eth2 -dontroute</pre><p>Appletalk networking should be enabled on all
three interfaces, but no routing should be done between the
different segments. Again, all the necessary configuration will be
fetched from the connected networks.</p></div><div class="example"><a name="id2836437"></a><p class="title"><b>Example3.4.atalkd.conf containing several entries with the -dontroute
option after atalkd started</b></p><pre class="programlisting">eth0 -dontroute -phase 2 -net 0-65534 -addr 65280.152
eth1 -dontroute -phase 2 -net 0-65534 -addr 65280.208
eth2 -dontroute -phase 2 -net 1-1000 -addr 10.142 -zone "Printers"</pre><p>
On eth0 and eth1, there are no other routers present, so atalkd
chooses an address from within the startup range. But on eth2
there lives an already connected AppleTalk router, publishing one
zone called "Printers" and forcing clients to assign themselves an
address in a netrange between 1 and 1000.</p></div><p>In this case, atalkd will handle each interface as it would be
the only active one. This can have some side effects when it comes
to the point where AFP clients want to do the magic switch from
AppleTalk to TCP, so use this with caution.</p></li></ul></div><p>In case, you have more than one active network interface and do
not take special precautions as outlined above, then autoconfiguration
of the interfaces might fail in a situation where one of your network
interfaces is connected to a network where <span class="emphasis"><em>no</em></span> other
active AppleTalk router is present and supplies appropriate routing
settings.</p><p>For further information see <a href="atalkd.conf.5.html"><span class="citerefentry"><span class="refentrytitle">atalkd.conf</span>(5)</span></a> and the developer documentation.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2836512"></a>atalkd acting as an AppleTalk router<a class="indexterm" name="id2836519"></a></h3></div></div><div></div></div><p>There exist several types of AppleTalk routers: seed, non-seed and
so called soft-seed routers.</p><div class="itemizedlist"><ul type="disc"><li><p>A seed router has its own configuration and publishes this
into the network segments it is configured for.</p></li><li><p>A non-seed router needs a seed router on the interface to
which it is connected to learn the network configuration. So this
type of AppleTalk router can work completely without manual
configuration.</p></li><li><p>A so called soft-seed router is exactly the same as a non-seed
router except the fact, that it can also remember the configuration
of a seed router and act as a replacement in case, the real seed
router disappears from the net.</p></li></ul></div><p>Netatalk's atalkd can act as both a seed and a soft-seed router,
even in a mixed mode, where it acts on one interface in this way and on
the other in another.</p><p>If you leave your atalkd.conf completely empty or simply add all
active interfaces line by line without using seed settings (atalkd will
act identically in both cases), then atalkd is forced to act as a
soft-seed router on each interface, so it will fail on the first
interface, where no seed router is accessible to fetch routing
information from.</p><p>In this case, other services, that depend on atalkd, might also
fail.</p><p>So you should have atalkd act as a seed router on one or all
active interfaces. A seed router has to supply informations
about:</p><div class="itemizedlist"><ul type="disc"><li><p>The specific netrange on this segment</p></li><li><p>Its own AppleTalk address</p></li><li><p>The zones (one to many) available in this segment</p></li><li><p>The so called "default zone" for this segment</p></li></ul></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>Unless you are the network admin yourself, consider asking
her/him before changing anything related to AppleTalk routing, as
changing these settings might have side effects for all of your
AppleTalk network clients!</p></div><p>In an AppleTalk network netranges have to be unique and must not
overlap each other. Fortunately netatalk's atalkd is polite enough to
check whether your settings are in conflict with already existing ones
on the net. In such a case it simply discards your settings and tries to
adapt the already established ones on the net (if in doubt, always check
syslog for details).</p><p>Netranges, you can use, include pretty small ones, eg. 42-42, to
very large ones, eg. 1-65279 - the latter one representing the maximum.
In routed environments you can use any numbers in the range between 1
and 65279 unless they do not overlap with settings of other connected
subnets.</p><p>The own AppleTalk address consists of a net part and a node part
(the former 16 bit, the latter 8 bit, for example 12057.143). Apple
recommends using node addresses of 128 or above for servers, letting
client Macs assign themselves an address faster (as they will primarily
search for a node address within 1-127 in the supplied netrange). As we
don't want to get in conflict with Apple servers, we prefer using node
addresses of 142 or above.</p><p>AppleTalk zones have <span class="emphasis"><em>nothing</em></span> to do with
physical networks. They're just a hint for your client's convenience,
letting them locate network resources in a more comfortable/faster way.
You can either use one zone name across multiple physical segments as
well as more than one zone name on a single segment (and various
combinations of this).</p><p>So all you have to do is to <span class="emphasis"><em>draw a network
chart</em></span> containing the physical segments, the netranges you
want to assign to each one, the zone names you want to publish in which
segments and the default zone per segment (this is always the first zone
name, you supply with the "-zone" switch in atalkd.conf).</p><p>Given, you finished the steps outlined above, you might want to
edit atalkd.conf to fit your needs.</p><p>You'll have to set the following options in atalkd.conf:</p><div class="itemizedlist"><ul type="disc"><li><p>-net (use reasonable values between 1-65279 for each
interface)</p><p>In case, this value is suppressed but -addr is present, the
netrange from this specific address will be used</p></li><li><p>-addr (the net part must match the -net settings if present,
the node address should be between 142 and 255)</p></li><li><p>-zone (can be used multiple times in one single line, the
first entry is the default zone)</p></li></ul></div><p>Note that you are able to set up "zone mapping", that means
publishing exactly the same zone name on all AppleTalk segments, as well
as providing more than one single zone name per interface. Dumb
AppleTalk devices, like LaserWriters, will always register themselves in
the default zone (the first zone entry you use in atalkd.conf per
interface), more intelligent ones will have the ability to choose one
specific zone via a user interface.</p><div class="example"><a name="id2836792"></a><p class="title"><b>Example3.5.atalkd.conf making netatalk a seed router on two
interfaces</b></p><pre class="programlisting">eth0 -seed -phase 2 -net 1-1000 -addr 1000.142 -zone "Printers" -zone "Spoolers"
eth1 -seed -phase 2 -net 1001-2000 -addr 2000.142 -zone "Macs" -zone "Servers"</pre><p>
The settings for eth0 force AppleTalk devices within the connected
network to assign themselves an address in the netrange 1-1000. Two
zone names are published into this segment, "Printers" being the so
called "standard zone", forcing dumb AppleTalk devices like Laser
printers to show up automatically into this zone. AppleTalk printer
queues supplied by netatalk's papd can be registered into the zone
"Spoolers" simply by adjusting the settings in <a href="papd.conf.5.html"><span class="citerefentry"><span class="refentrytitle">papd.conf</span>(5)</span></a>. On eth1 we use the different and non-overlapping
netrange 1001-2000, set the default zone to "Macs" and publish a
fourth zone name "Servers".</p></div><div class="example"><a name="id2836841"></a><p class="title"><b>Example3.6.atalkd.conf configured for "zone mapping"</b></p><pre class="programlisting">eth0 -seed -phase 2 -net 1-1000 -addr 1000.142 -zone "foo"
lo0 -phase 1 -net 1 -addr 1.142 -zone "foo"</pre><p> We use the same
network settings as in the example above but let atalkd publish the
same zone name on both segments. As the same zone name will be used on
all segments of the AppleTalk network no zone names will show up at
all... but AppleTalk routing will still be active. In this case, we
connect a so called "non-extended" LocalTalk network (phase 1) to an
EtherTalk "extended" network (phase 2) transparently.</p></div><div class="example"><a name="id2836872"></a><p class="title"><b>Example3.7.atalkd.conf for a soft-seed router configuration</b></p><pre class="programlisting">eth0
eth1
eth2</pre><p> As we have more than one interface, atalkd will try to
act as an AppleTalk router between both segments. As we don't supply
any network configuration on our own we depend on the availability of
seed routers in every connected segment. If only one segment is
without such an available seed router the whole thing will
fail.</p></div><div class="example"><a name="id2836897"></a><p class="title"><b>Example3.8.atalkd.conf for a soft-seed router configuration after atalkd
started</b></p><pre class="programlisting">eth0 -phase 2 -net 10-10 -addr 10.166 -zone "Parking"
eth1 -phase 2 -net 10000-11000 -addr 10324.151 -zone "No Parking" -zone "Parking"
eth2 -phase 2 -net 65279-65279 -addr 65279.142 -zone "Parking" -zone "No Parking"</pre><p>
In this case, active seed routers are present in all three connected
networks, so atalkd was able to fetch the network configuration from
them and, since the settings do not conflict, act as a soft-seed
router from now on between the segments. So even in case, all of the
three seed routers would disappear from the net, atalkd would still
supply the connected network with the network configuration once
learned from them. Only in case, atalkd would be restarted afterwards,
the routing information will be lost (as we're not acting as seed
router).</p></div><div class="example"><a name="id2836945"></a><p class="title"><b>Example3.9.atalkd.conf ready for mixed seed/soft-seed mode</b></p><pre class="programlisting">eth0
eth1 -seed -phase 2 -net 99-100 -addr 99.200 -zone "Testing"</pre><p>
In case in the network connected to eth0 lives no active seed router
or one with a mismatching configuration (eg. an overlapping netrange
of 1-200) atalkd will fail. Otherwise it will fetch the configuration
from this machine and will route between eth0 and eth1, on the latter
acting as a seed router itself.</p></div><p>By the way: It is perfectly legal to have more than one seed
router connected to a network segment. But in this case, you should take
care that the configuration of all connected routers is exactly the same
regarding netranges, published zone names and also the "standard zone"
per segment</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2836984"></a>File Services<a class="indexterm" name="id2836990"></a></h2></div></div><div></div></div><p>Netatalk supplies two different transport protocols for
AFP<a class="indexterm" name="id2837009"></a> services and both can run at the same time. Classic AFP
over AppleTalk requires the <span><b class="command">afpd</b></span> and
<span><b class="command">atalkd</b></span> daemons. AFP over IP only requires
<span><b class="command">afpd</b></span>.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2837047"></a>Setting up the AFP file server</h3></div></div><div></div></div><p>AFP (the Apple Filing Protocol) is the protocol Apple Macintoshes
use for file services. The protocol has evolved over the years, at the
time of this writing 7 different "versions" exist. The latest changes to
the protocol, called "AFP 3.1", were added with the release of
Panther<a class="indexterm" name="id2837064"></a> (Mac OS X 10.3).</p><p>AFP3 brought some big changes. For the first time,
AppleShare<a class="indexterm" name="id2837085"></a> Clients can use filenames up to 255 characters (actually
255 bytes leading to 85-255 chars depending on the glyphs used), UTF-8
is used on the wire and large files (>4GB) are supported.</p><p>The afpd daemon offers the fileservices to Apple Clients. It's
configured using the <tt class="filename">afpd.conf</tt> and the
<tt class="filename">AppleVolumes.*</tt> files.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2896530"></a>afpd.conf</h4></div></div><div></div></div><p>afpd.conf is the configuration file used by afpd to determine
the behaviour and configuration of the different virtual file servers
that it provides. Any line not prefixed with <span class="keycode">'#</span>' is
interpreted.</p><p>If afpd switches set on the command line are in conflict with
afpd.conf settings, the latter will have higher priority.</p><p>Format: - [options] to specify options for the default server
and/or "Server name" [options] to specify an additional server.</p><p>Leaving the afpd.conf file empty equals to the following
configuration:</p><pre class="programlisting">- -transall -uamlist uams_guest.so,uams_clrtxt.so,uams_dhx.so -nosavepassword</pre><p>For a more detailed explanation of the available options, please
refer to the <a href="afpd.conf.5.html"><span class="citerefentry"><span class="refentrytitle">afpd.conf</span>(5)</span></a> man page.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2896598"></a>AppleVolumes.default</h4></div></div><div></div></div><p>The AppleVolumes.default file is used to define volumes that
will by default be shown to all users, including users logged in as
guest. A volume will not be presented in the chooser, if the user has
no read access to the specified volume path.</p><p>You can limit access to a specific volume by using the
<tt class="option">allow</tt> and <tt class="option">deny</tt> options.</p><p>For a more detailed explanation of the available options, please
refer to the <a href="AppleVolumes.default.5.html"><span class="citerefentry"><span class="refentrytitle">AppleVolumes.default</span>(5)</span></a> man page.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="CNID-backends"></a>CNID<a class="indexterm" name="id2896660"></a> backends<a class="indexterm" name="id2896675"></a></h3></div></div><div></div></div><p>Unlike other protocols like smb or nfs, the AFP protocol mostly
refers to files and directories by ID and not by a path (the IDs are
also called CNID, that means Catalog Node ID). A typical AFP request
uses a directory ID<a class="indexterm" name="id2896698"></a> and a filename, something like <span>"server, please
open the file named 'Test' in the directory with id 167"</span>. For
example "Aliases" on the Mac basically work by ID (with a fallback to
the absolute path in more recent AFP clients. But this applies only to
Finder, not to applications).</p><p>Every file in an AFP volume has to have a unique file ID<a class="indexterm" name="id2896728"></a>, IDs must, according to the specs, never be reused, and
IDs are 32 bit numbers (Directory IDs use the same ID pool). So, after
~4 billion files/folders have been written to an AFP volume, the ID pool
is depleted and no new file can be written to the volume. No whining
please :-)</p><p>Netatalk needs to map IDs to files and folders in the host
filesystem. To achieve this, several different CNID backends<a class="indexterm" name="id2896756"></a> are available and can be choosed by the
<tt class="option">cnidscheme</tt><a class="indexterm" name="id2896771"></a> option in the <a href="AppleVolumes.default.5.html"><span class="citerefentry"><span class="refentrytitle">AppleVolumes.default</span>(5)</span></a> configuration file. A CNID backend is basically a
database storing ID <-> name mappings.</p><p>In the past, many users used the so called "last" CNID scheme.
However, this scheme has some serious drawbacks, as it is based on the
device and inode of a file. Therefore, IDs will be eventually be reused
and you can get duplicate IDs as well.</p><p>The CNID Databases are by default located in the
.AppleDB<a class="indexterm" name="id2896817"></a> folder in every afpd volume root. With the new
ADv2<a class="indexterm" name="id2896834"></a> format, afpd stores the files/directories ID in the
corresponding .AppleDouble file as well.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>There are some CNID related things you should keep in mind when
working with netatalk:</p><div class="itemizedlist"><ul type="disc"><li><p>Don't use unix symlinks<a class="indexterm" name="id2896871"></a>. Just don't. With a symlink a file/directory
"exists" twice, something AFP doesn't allow. There's currently no
way this can be resolved, as we either end up with two file/dirs
having the same id, or a file having two parents. If you still
insist on using them, be aware you're <span class="emphasis"><em>heavily</em></span>
violating the specs. You have been warned...</p></li><li><p>Don't nest volumes<a class="indexterm" name="id2896907"></a>.</p></li><li><p>CNID backends are databases, so they turn afpd into a file
server/database mix. Keep this in mind, killing an afpd process
with <span><b class="command">kill -9</b></span> will likely leave the database
unusable.</p></li><li><p>If there's no more space on the filesystem left, the
database will get corrupted. You can work around this by either
using the -dbpath option and put the database files into another
location or, if you use quotas, make sure the .AppleDB folder is
owned by a user/group without a quota<a class="indexterm" name="id2896952"></a>.</p></li><li><p>Be careful with CNID databases for volumes that are mounted
via NFS. That is a pretty audacious decision to make anyway, but
putting a database there as well is really asking for trouble,
i.e. database corruption. Use the dbpath: directive in the
<tt class="filename">AppleVolumes.*</tt> configuration files to put the
databases onto a local disk if you must use NFS<a class="indexterm" name="id2896991"></a> mounted volumes.</p></li></ul></div></div><p></p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2897013"></a>cdb<a class="indexterm" name="id2897020"></a></h4></div></div><div></div></div><p>The "concurrent database" backend is based on sleepycat's
Berkeley DB. With this backend, several afpd daemons access the CNID
database directly. Berkeley DB locking is used to synchronize access,
if more than one afpd process is active for a volume. The drawback is,
that the crash of a single afpd process might corrupt the
database.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2897047"></a>dbd<a class="indexterm" name="id2897054"></a></h4></div></div><div></div></div><p>Access to the CNID database is restricted to the cnid_dbd daemon
process. afpd processes communicate with the daemon for database reads
and updates. If built with Berkeley DB transactions, the probability
for database corruption is practically zero, but performance can be
slower than with cdb. As a database process gets spawned for each
volume, you're probably better off using cdb for sharing home
directories for a larger number of users.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2897092"></a>last<a class="indexterm" name="id2897099"></a></h4></div></div><div></div></div><p>The last backend is a semi-persistent backend. IDs will be
reused and, what is much worse, you can get duplicate IDs. You should
use it for sharing cdroms only, <span class="emphasis"><em>don't</em></span> use it for
sharing normal volumes.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="charsets"></a>Charsets<a class="indexterm" name="id2897139"></a>/Unicode<a class="indexterm" name="id2897154"></a></h3></div></div><div></div></div><p></p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2897167"></a>Why Unicode?</h4></div></div><div></div></div><p>Internally, computers don't know anything about characters and
texts, they only know numbers. Therefore, each letter is assigned a
number. A character set, often referred to as
<span class="emphasis"><em>charset</em></span> or
<span class="emphasis"><em>codepage</em></span><a class="indexterm" name="id2897189"></a>, defines the mappings between numbers and
letters.</p><p>If two or more computer systems need to communicate with each
other, the have to use the same character set. In the 1960s the
ASCII<a class="indexterm" name="id2897208"></a> (American Standard Code for Information Interchange)
character set was defined by the American Standards Association. The
original form of ASCII represented 128 characters, more than enough to
cover the English alphabet and numerals. Up to date, ASCII has been
the normative character scheme used by computers.</p><p>Later versions defined 256 characters to produce a more
international fluency and to include some slightly esoteric graphical
characters. Using this mode of encoding each character takes exactly
one byte. Obviously, 256 characters still wasn't enough to map all the
characters used in the various languages into one character
set.</p><p>As a result localized character sets were defined later, e.g the
ISO-8859 character sets. Most operating system vendors introduced
their own characters sets to satisfy their needs, e.g. IBM defined the
<span class="emphasis"><em>codepage 437 (DOSLatinUS)</em></span>, Apple introduced the
<span class="emphasis"><em>MacRoman</em></span><a class="indexterm" name="id2897258"></a> codepage and so on. The characters that were assigned
number larger than 127 were referred to as
<span class="emphasis"><em>extended</em></span> characters. These character sets
conflict with another, as they use the same number for different
characters, or vice versa.</p><p>Almost all of those characters sets defined 256 characters,
where the first 128 (0-127) character mappings are identical to ASCII.
As a result, communication between systems using different codepages
was effectively limited to the ASCII charset.</p><p>To solve this problem new, larger character sets were defined.
To make room for more character mappings, these character sets use at
least 2 bytes to store a character. They are therefore referred to as
<span class="emphasis"><em>multibyte</em></span> character sets.</p><p>One standardized multibyte charset encoding scheme is known as
<a href="http://www.unicode.org/" target="_top">unicode</a>. A big advantage
of using a multibyte charset is that you only need one. There is no
need to make sure two computers use the same charset when they are
communicating.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2897322"></a>character sets used by Apple</h4></div></div><div></div></div><p>In the past, Apple clients used single-byte charsets to
communicate over the network. Over the years Apple defined a number of
codepages, western users will most likely be using the
<span class="emphasis"><em>MacRoman</em></span> codepage.</p><p>Codepages defined by Apple include:</p><div class="itemizedlist"><ul type="disc"><li><p>MacArabic, MacFarsi</p></li><li><p>MacCentralEurope</p></li><li><p>MacChineseSimple</p></li><li><p>MacChineseTraditional</p></li><li><p>MacCroation</p></li><li><p>MacCyrillic</p></li><li><p>MacDevanagari</p></li><li><p>MacGreek</p></li><li><p>MacHebrew</p></li><li><p>MacIcelandic</p></li><li><p>MacKorean</p></li><li><p>MacJapanese</p></li><li><p>MacRoman</p></li><li><p>MacRomanian</p></li><li><p>MacThai</p></li><li><p>MacTurkish</p></li></ul></div><p>Starting with Mac OS X and AFP3, <a href="http://www.utf-8.com/" target="_top">UTF-8</a> is used. UTF-8 encodes
Unicode characters in an ASCII compatible way, each Unicode character
is encoded into 1-6 ASCII characters. UTF-8 is therefore not really a
charset itself, it's an encoding of the Unicode charset.</p><p>To complicate things, Unicode defines several <span class="emphasis"><em><a href="http://www.unicode.org/reports/tr15/index.html" target="_top">normalization</a></em></span>
forms. While <a href="http://www.samba.org" target="_top">samba</a><a class="indexterm" name="id2897526"></a> uses <span class="emphasis"><em>precomposed</em></span><a class="indexterm" name="id2897539"></a> Unicode, which most Unix tools prefer as well, Apple
decided to use the <span class="emphasis"><em>decomposed</em></span><a class="indexterm" name="id2897559"></a> normalization.</p><p>For example lets take the German character
'<span class="keycode"></span>'. Using the precomposed normalization, Unicode
maps this character to 0xE4. In decomposed normalization, '' is
actually mapped to two characters, 0x61 and 0x308. 0x61 is the mapping
for an 'a', 0x308 is the mapping for a <span class="emphasis"><em>COMBINING
DIAERESIS</em></span>.</p><p>Netatalk refers to precomposed UTF-8 as
<span class="emphasis"><em>UTF8</em></span><a class="indexterm" name="id2897611"></a> and to decomposed UTF-8 as
<span class="emphasis"><em>UTF8-MAC</em></span><a class="indexterm" name="id2897630"></a>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2897647"></a>afpd and character sets</h4></div></div><div></div></div><p>To support new AFP 3.x and older AFP 2.x clients at the same
time, afpd needs to be able to convert between the various charsets
used. AFP 3.x clients always use UTF-8, AFP 2.2 clients use one of the
Apple codepages.</p><p>At the time of this writing, netatalk supports the following
Apple codepages:</p><div class="itemizedlist"><ul type="disc"><li><p>MAC_CENTRALEUROPE</p></li><li><p>MAC_CYRILLIC</p></li><li><p>MAC_HEBREW</p></li><li><p>MAC_ROMAN</p></li><li><p>MAC_TURKISH</p></li></ul></div><p>afpd handles three different character set options:</p><div class="variablelist"><dl><dt><span class="term">unixcodepage<a class="indexterm" name="id2897733"></a></span></dt><dd><p>This is the codepage used internally by your operating
system. If not specified and your system support Unix locales,
afpd tries to detect the codepage, otherwise it defaults to
ASCII<a class="indexterm" name="id2897760"></a>. afpd uses this codepage to read its
configuration files, so you can use extended characters for
volume names, login messages, etc. see <a href="afpd.conf.5.html"><span class="citerefentry"><span class="refentrytitle">afpd.conf</span>(5)</span></a>.</p></dd><dt><span class="term">maccodepage<a class="indexterm" name="id2897806"></a></span></dt><dd><p>As already mentioned, older MacOS clients (up to AFP 2.2)
use codepages to communicate with afpd. However, there is no
support for negotiating the codepage used by the client in the
AFP protocol. If not specified otherwise, afpd assumes the
<span class="emphasis"><em>MacRoman</em></span> codepage is used. In case you're
clients use another codepage, e.g.
<span class="emphasis"><em>MacCyrillic</em></span>, you'll <span class="bold"><b>have</b></span> to explicitly configure this. see
<a href="afpd.conf.5.html"><span class="citerefentry"><span class="refentrytitle">afpd.conf</span>(5)</span></a>.</p></dd><dt><span class="term">volcharset<a class="indexterm" name="id2897872"></a></span></dt><dd><p>This defines the charset afpd should use for filenames on
disk. The default is UTF8. If you have <a href="http://www.gnu.org/software/libiconv/" target="_top">iconv</a><a class="indexterm" name="id2897904"></a> installed, you can use any iconv provided charset
as well.</p><p>afpd needs a way to preserve extended macintosh
characters, or characters illegal in unix filenames, when saving
files on a unix filesystem. Earlier versions used the the so
called CAP encoding<a class="indexterm" name="id2897929"></a>. An extended character (>0x7F) would be
converted to a :xx hex sequence, e.g. the Apple Logo (MacRoman:
0XF0) was saved as :f0. Some special characters will be
converted as to :xx notation as well. '/' will be encoded to
:2f, if -usedots is not specified, a leading dot '.' will be
encoded as :2e. Even though this version now uses UTF-8 as the
default encoding for filenames, special characters, like '/' and
a leading '.' will still be CAP style encoded. For western users
another useful setting could be <span class="emphasis"><em>-volcharset
ISO-8859-15</em></span>.</p><p>If a character cannot be converted from the mac codepage
to the selected volcharset, afpd will save it as a CAP encoded
character. For AFP3 clients, afpd will convert the UTF-8
character to <span class="emphasis"><em>maccodepage</em></span> first. If this
conversion fails, you'll receive a -50 error on the mac.
<span class="emphasis"><em>Note</em></span>: Whenever you can, please stick with
the default UTF-8 volume format. see <a href="AppleVolumes.default.5.html"><span class="citerefentry"><span class="refentrytitle">AppleVolumes.default</span>(5)</span></a>.</p></dd></dl></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="authentication"></a>Authentication<a class="indexterm" name="id2898026"></a></h3></div></div><div></div></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2898040"></a>AFP authentication basics</h4></div></div><div></div></div><p>Apple chose a flexible model called "User Authentication
Modules"<a class="indexterm" name="id2898053"></a> (UAMs) for authentication purposes between AFP client
and server. An AFP client initially connecting to an AFP server will
ask for the list of UAMs which the server provides, and will choose
the one with strongest encryption that the client supports.</p><p>Several UAMs have been developed by Apple over the time, some by
3rd-party developers.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2898081"></a>UAMs supported by Netatalk</h4></div></div><div></div></div><p>Netatalk supports the following ones by default:</p><div class="itemizedlist"><ul type="disc"><li><p>"No User Authent"<a class="indexterm" name="id2898104"></a> UAM (guest access without authentication)</p></li><li><p>"Cleartxt Passwrd"<a class="indexterm" name="id2898130"></a> UAM (no password encryption)</p></li><li><p>"Randnum exchange"<a class="indexterm" name="id2898156"></a>/"2-Way Randnum exchange"<a class="indexterm" name="id2898172"></a> UAMs (weak password encryption, separate password
storage)</p></li><li><p>"DHCAST128"<a class="indexterm" name="id2898198"></a> UAM (stronger password encryption, should be used
these days)</p></li></ul></div><p>There exist other optional UAMs as well:</p><div class="itemizedlist"><ul type="disc"><li><p>"PGPuam 1.0"<a class="indexterm" name="id2898233"></a><a class="indexterm" name="id2898248"></a> UAM (PGP-based authentication for pre-Mac OS X
clients. You'll also need the <a href="http://www.vmeng.com/vinnie/papers/pgpuam.html" target="_top">PGPuam
client</a> to let this work)</p><p>You'll have to add <tt class="filename">"--enable-pgp-uam"</tt>
to your configure switches to have this UAM available.</p></li><li><p>"Kerberos IV"<a class="indexterm" name="id2898294"></a><a class="indexterm" name="id2898309"></a>/"AFS Kerberos"<a class="indexterm" name="id2898325"></a> UAMs (suitable to use <a href="http://web.mit.edu/macdev/KfM/Common/Documentation/faq.html" target="_top">Kerberos
v4 based authentication</a> and AFS file servers)</p><p>Use <tt class="filename">"--enable-krb4-uam"</tt> at compile time
to activate the build of this UAM.</p></li><li><p>"Client Krb v2"<a class="indexterm" name="id2898372"></a> UAM (Kerberos V, suitable for "Single Sign On"
Scenarios with Mac OS X clients -- see below)</p><p><tt class="filename">"--enable-krbV-uam"</tt> will provide you
with the ability to use this UAM.</p></li></ul></div><p>You can configure which UAMs should be activated by defining
<tt class="filename">$AFPD_UAM_LIST</tt> in <a href="netatalk.conf.5.html"><span class="citerefentry"><span class="refentrytitle">netatalk.conf</span>(5)</span></a>. <span><b class="command">afpd</b></span> will log which UAMs it's
using and if problems occur while activating them in either
<tt class="filename">netatalk.log</tt> or syslog at startup time.
<a href="asip-status.pl.1.html"><span class="citerefentry"><span class="refentrytitle">asip-status.pl</span>(1)</span></a> can be used to query the available UAMs of AFP
servers as well.</p><p>Having a specific UAM available at the server does not
automatically mean that a client can use it. Client-side support is
also necessary. Fortunately this isn't such a problem these days since
Mac OS X' AFP-client supports DHCAST128 from the beginning on. For
older Macintoshes running Mac OS < X DHCAST128 support exists since
AppleShare client 3.8.x.</p><p>On Mac OS X, there exist some client-side techniques to make the
AFP-client more verbose, so one can have a look what's happening while
negotiating the UAMs to use. Compare with this <a href="http://article.gmane.org/gmane.network.netatalk.devel/7383/" target="_top">hint</a>.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2898494"></a>Which UAMs to activate?</h4></div></div><div></div></div><p>It depends primarily on your needs and on the kind of Mac OS
versions you have to support. Basically one should try to use
DHCAST128 where possible because of its strength of password
encryption.</p><div class="itemizedlist"><ul type="disc"><li><p>Unless you really have to supply guest access to your
server's volumes ensure that you disable "No User Authent" since
it might lead accidentally to unauthorized access. In case you
must enable guest access take care that you enforce this on a per
volume base using the access controls the <a href="AppleVolumes.default.5.html"><span class="citerefentry"><span class="refentrytitle">AppleVolumes.default</span>(5)</span></a> config file supplies or think about setting up
an own server definition serving these public shares in
<a href="afpd.conf.5.html"><span class="citerefentry"><span class="refentrytitle">afpd.conf</span>(5)</span></a>.</p></li><li><p>The "ClearTxt Passwrd" UAM is as bad as it sounds since
passwords go unencrypted over the wire. Try to avoid it at both
the server's side as well as on the client's. Note: If you want to
provide Mac OS 8/9 clients with NetBoot-services then you need
uams_cleartext.so since the AFP-client integrated into the Mac's
firmware can only deal with this basic form of
authentication.</p></li><li><p>Since "Randnum exchange"/"2-Way Randnum exchange" uses only
56 bit DES for encryption it should be avoided as well. Another
disadvantage is the fact that the passwords have to be stored in
cleartext on the server and that it doesn't integrate into both
PAM scenarios or classic /etc/shadow (you have to administrate
passwords separately by using the <a href="afppasswd.1.html"><span class="citerefentry"><span class="refentrytitle">afppasswd</span>(1)</span></a> utility, if clients should use these
UAMs)</p></li><li><p>"DHCAST128" should be a good compromise for most people
since it combines stronger encryption with PAM integration.
Hopefully Netatalk will support its successor "DHX2" (Diffie
Hellman Exchange 2) in the future, which provides even stronger
encryption.</p></li><li><p>Using the Kerberos V<a class="indexterm" name="id2898624"></a> ("Client Krb v2") UAM, it's possible to implement
real single sign on scenarios using Kerberos tickets. The password
is not sent over the network. Instead, the user password is used
to decrypt a service ticket for the appleshare server. The service
ticket contains an encryption key for the client and some
encrypted data (which only the appleshare server can decrypt). The
encrypted portion of the service ticket is sent to the server and
used to authenticate the user. Because of the way that the afpd
service principal detection is implemented, this authentication
method is vulnerable to man-in-the-middle attacks.</p></li></ul></div><p>For a more detailed overview over the technical implications of
the different UAMs, please have a look at Apple's <a href="http://developer.apple.com/documentation/Networking/Conceptual/AFP/Chapter_1/chapter_2_section_6.html" target="_top">File
Server Security</a> pages.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2898674"></a>Using different authentication sources with specific
UAMs</h4></div></div><div></div></div><p>Some UAMs provide the ability to use different authentication
"backends", namely <tt class="filename">uams_cleartext.so</tt> and
<tt class="filename">uams_dhx.so</tt>. They can both use either classic
Unix passwords from <tt class="filename">/etc/passwd</tt>
(<tt class="filename">/etc/shadow</tt>) or PAM if the system supports that.
<tt class="filename">uams_cleartext.so</tt> can be symlinked to either
<tt class="filename">uams_passwd.so</tt> or
<tt class="filename">uams_pam.so</tt>, <tt class="filename">uams_dhx.so</tt> to
<tt class="filename">uams_dhx_passwd.so</tt> or
<tt class="filename">uams_dhx_pam.so</tt>. So, if it looks like this in
Netatalk's UAMs folder (per default
<tt class="filename">/etc/netatalk/uams/</tt>):</p><pre class="programlisting">uams_clrtxt.so -> uams_pam.so
uams_dhx.so -> uams_dhx_pam.so</pre><p> then you're using PAM,
otherwise classic Unix passwords. The main advantage of using PAM is
that one can integrate Netatalk in centralized authentication
scenarios, eg. via LDAP, NIS and the like. Please always keep in mind
that the protection of your user's login credentials in such scenarios
also depends on the strength of encryption that the UAM in question
supplies. So think about eliminating weak UAMs like "ClearTxt Passwrd"
and "Randnum exchange" completely from your network.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="id2898789"></a>Netatalk UAM overview table</h4></div></div><div></div></div><p>A small overview of the most common used UAMs.</p><div class="table"><a name="id2898801"></a><p class="title"><b>Table3.1.Netatalk UAM overview</b></p><table summary="Netatalk UAM overview" border="1"><colgroup><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"><col align="center"></colgroup><tbody><tr><td align="center" valign="middle">UAM</td><td align="center">No User Authent<a class="indexterm" name="id2898907"></a></td><td align="center">Cleartxt Passwrd<a class="indexterm" name="id2898926"></a></td><td align="center">(2-Way) Randnum exchange<a class="indexterm" name="id2898946"></a></td><td align="center">DHCAST128<a class="indexterm" name="id2898966"></a></td><td align="center">Client Krb v2<a class="indexterm" name="id2898985"></a></td></tr><tr><td align="center" valign="middle">pssword
length</td><td align="center">guest access</td><td align="center">max. 8 characters</td><td align="center">max. 8 characters</td><td align="center">max. 64 characters</td><td align="center">Kerberos tickets</td></tr><tr><td align="center" valign="middle">Client
support</td><td align="center">built-in into all Mac OS versions</td><td align="center">built-in in all Mac OS versions except 10.0. Has to be
activated explicitly in recent Mac OS X versions</td><td align="center">built-in into almost all Mac OS versions</td><td align="center">built-in since AppleShare client 3.8.4, available as a
plug-in for 3.8.3, integrated in Mac OS X' AFP client</td><td align="center">built-in since MacOS X 10.2</td></tr><tr><td align="center" valign="middle">Encryption</td><td align="center">Enables guest access without authentication between
client and server.</td><td align="center">Password will be sent in cleartext over the wire. Just
as bad as it sounds, therefore avoid at all if possible (note:
providing NetBoot services requires the ClearTxt UAM)</td><td align="center">8-byte random numbers are sent over the wire,
comparable with DES, 56 bits. Vulnerable to offline dictionary
attack. Requires passwords in clear on the server.</td><td align="center">Password will be encrypted with 128 bit SSL, user will
be authenticated against the server but not vice versa.
Therefor weak against man-in-the-middle attacks.</td><td align="center">Password is not sent over the network. Due to the
service principal detection method, this authentication method
is vulnerable to man-in-the-middle attacks.</td></tr><tr><td align="center" valign="middle">Server
support</td><td align="center" valign="middle">uams_guest.so</td><td align="center" valign="middle">uams_cleartxt.so</td><td align="center" valign="middle">uams_randnum.so</td><td align="center" valign="middle">uams_dhx.so</td><td align="center" valign="middle">uams_gss.so</td></tr><tr><td align="center" valign="middle">Password
storage method</td><td align="center" valign="middle">None</td><td align="center" valign="middle">Either /etc/passwd
(/etc/shadow) or PAM</td><td align="center" valign="middle">Passwords stored in
clear text in a separate text file</td><td align="center" valign="middle">Either /etc/passwd
(/etc/shadow) or PAM</td><td align="center" valign="middle">At the Kerberos Key
Distribution Center*</td></tr></tbody></table></div><p>* Have a look at this <a href="http://cryptnet.net/fdp/admin/kerby-infra/en/kerby-infra.html" target="_top">Kerberos
overview</a></p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="sshtunnel"></a>SSH tunneling</h4></div></div><div></div></div><p>Tunneling and all sort of VPN stuff has nothing to do with AFP
authentication and UAMs in general. But since Apple introduced an
option called "Allow Secure Connections Using SSH" and many people
tend to confuse both things, we'll speak about that here too.</p><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="manualsshtunnel"></a>Manually tunneling an AFP session</h5></div></div><div></div></div><p>This works since the first AFP servers that spoke "AFP over
TCP" appeared in networks. One simply tunnels the remote server's
AFP port to a local port different than 548 and connects locally to
this port afterwards. On MacOS X this can be done by</p><pre class="programlisting">ssh -l $USER $SERVER -L 10548:127.0.0.1:548 sleep 3000</pre><p>After establishing the tunnel one will use
<tt class="filename">"afp://127.0.0.1:10548"</tt> in the "Connect to
server" dialog. All AFP traffic including the initial connection
attempts will be sent encrypted over the wire since the local AFP
client will connect to the Mac's local port 10548 which will be
forwarded to the remote server's AFP port (we used the default 548)
over SSH.</p><p>These sorts of tunnels are an ideal solution if you've to
access an AFP server providing weak authentications mechanisms
through the Internet without having the ability to use a "real" VPN.
Note that you can let <span><b class="command">ssh</b></span> compress the data by
using its "-C" switch and that the tunnel endpoints can be different
from both AFP client and server (compare with the SSH documentation
for details).</p></div><div class="sect4" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="autosshtunnel"></a>Automatically establishing a tunneled AFP connection</h5></div></div><div></div></div><p>Starting with Mac OS X 10.2 Apple added an "Allow Secure
Connections Using SSH" checkbox to the "Connect to Server" dialog.
The idea behind: When the server signals that it can be contacted by
SSH then Mac OS X' AFP client tries to establish the tunnel and
automagically sends all AFP traffic through it.</p><p>But it took until the release of Mac OS X 10.3 that this
feature worked the first time... partly. In case, the SSH tunnel
can't be established the AFP client <span class="strong">silently</span> fell back to an unencrypted AFP
connection attempt.</p><p>Netatalk's afpd will report that it is capable of handling SSH
tunneled AFP requests, when both <tt class="filename">-advertise_ssh</tt>
and <tt class="filename">-fqdn</tt> options are set in <a href="afpd.conf.5.html"><span class="citerefentry"><span class="refentrytitle">afpd.conf</span>(5)</span></a> (double check with <a href="asip-status.pl.1.html"><span class="citerefentry"><span class="refentrytitle">asip-status.pl</span>(1)</span></a> after you restarted afpd when you made changes to
the settings). But there are a couple of reasons why you don't want
to use this option at all:</p><div class="itemizedlist"><ul type="disc"><li><p>Tunneling TCP over TCP (as SSH does) is not the best idea.
There exist better solutions like VPNs based on the IP
layer.</p></li><li><p>Since this SSH kludge isn't a normal UAM that integrates
directly into the AFP authentication mechanisms but instead uses
a single flag signalling clients whether they can <span class="strong">try</span> to establish a tunnel or not, it
makes life harder to see what's happening when things go
wrong.</p></li><li><p>You cannot control which machines are logged on by
Netatalk tools like <span><b class="command">nu</b></span> or
<span><b class="command">macusers</b></span> since all connection attempts seem
to be made from localhost.</p></li><li><p>On the other side you've to limit access to afpd to
localhost only (TCP wrappers) and disable AFP over DDP when you
want to ensure that all AFP sessions are SSH encrypted
or...</p></li><li><p>...when you're using 10.2 - 10.3.3 then you get the
opposite of what you'd expect: potentially unencrypted AFP
communication (including logon credentials) on the network
without a single notification that establishing the tunnel
failed. Apple fixed that not until Mac OS X 10.3.4.</p></li><li><p>Encrypting all AFP sessions via SSH can lead to a
significantly higher load on the Netatalk server</p></li></ul></div></div></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="printing"></a>Printing<a class="indexterm" name="id2899584"></a></h2></div></div><div></div></div><p>Netatalk can act as both a PAP<a class="indexterm" name="id2899598"></a> client to access AppleTalk-capable printers and a PAP
server. The former by using the <a href="pap.1.html"><span class="citerefentry"><span class="refentrytitle"><span><b class="command">pap</b></span></span>(1)</span></a> utility and the latter by starting the <a href="papd.8.html"><span class="citerefentry"><span class="refentrytitle"><span><b class="command">papd</b></span></span>(8)</span></a> service.</p><p>The "Printer Access Protocol" as part of the AppleTalk protocol
suite is a fully 8 bit aware and bidirectional printing protocol,
developed by Apple in 1985. <span class="emphasis"><em>8 bit aware</em></span> means that
the whole set of bytes can be used for printing (binary encoding). This
has been a great advantage compared with other protocols like Adobe's
Standard Protocol to drive serial and parallel PostScript printers
(compare with <a href="http://partners.adobe.com/asn/tech/ps/specifications.jsp" target="_top">Adobe
TechNote 5009</a>) or LPR<a class="indexterm" name="id2899675"></a> which made only use of the lower 128 bytes for printing
because the 8th bit has been reserved for control codes.</p><p><span class="emphasis"><em>Bidirectional</em></span> means that printing source
(usually a Macintosh computer) and destination (a printer or spooler
implementation) communicate about both destination's capabilities via
feature queries (compare with <a href="http://partners.adobe.com/asn/tech/ps/archive.jsp" target="_top">Adobe TechNote
5133</a>) and device status. This allows the LaserWriter driver on the
Macintosh to generate appropriate device specific PostScript code (color
or b/w, only embedding needed fonts, and so on) on the one hand and
notifications about the printing process or problems (paper jam for
example) on the other.</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="papserver"></a>Setting up the PAP print server</h3></div></div><div></div></div><p>Netatalk's <span><b class="command">papd</b></span> is able to provide AppleTalk
printing services for Macintoshes or, to be more precise, PAP clients in
general. Netatalk does not contain a full-blown spooler implementation
itself, papd only handles the bidirectional communication and
submittance of printjobs from PAP clients. So normally one needs to
integrate papd with a Unix printing system like eg. classic SysV
lpd<a class="indexterm" name="id2899746"></a>, BSD lpr<a class="indexterm" name="id2899762"></a>, LPRng<a class="indexterm" name="id2899777"></a>, CUPS<a class="indexterm" name="id2899793"></a> or the like.</p><p>Since it is so important to answer the client's feature queries
correctly, how does papd achieve this? By parsing the relevant keywords
of the assigned PPD<a class="indexterm" name="id2899816"></a> file. That said, it's always necessary to carefully
choose the right PPD at the server's side.</p><p>Netatalk formerly had built-in support for System V lpd printing
in a way that papd saved the printed job directly into the spooldir and
calls <span><b class="command">lpd</b></span> afterwards, to pick up the file and do the
rest. Due to incompatibilities with many lpd implementations the normal
behaviour was to print directly into a pipe instead of specifying a
printer by name and using lpd interaction. With Netatalk 2.0 another
alternative has been implemented: direct interaction with CUPS (Note:
when CUPS support is compiled in, then the SysV lpd support doesn't work
at all). Detailed examples can be found in the <a href="papd.conf.5.html"><span class="citerefentry"><span class="refentrytitle">papd.conf</span>(5)</span></a> manual page.</p><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="paplpdsupport"></a>Integrating <span><b class="command">papd</b></span> with SysV lpd</h4></div></div><div></div></div><p>Unless CUPS support has been compiled in (which is default from
Netatalk 2.0 on) one simply defines the lpd queue in question by
setting the <tt class="option">pr</tt> parameter to the queue name. If no
<tt class="option">pr</tt> parameter is set, the default printer will be
used.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="pappipesupport"></a>Using pipes with <span><b class="command">papd</b></span></h4></div></div><div></div></div><p>An alternative to the technique outlined above is to direct
papd's output via a pipe into another program. Using this mechanism
almost all printing systems can be driven. Netatalk supplies three
"wildcards" that get substituted with values of the already printed
job:</p><div class="variablelist"><dl><dt><span class="term">%F</span></dt><dd><p>will be substituted with the contents of the
<span class="emphasis"><em>%%For:</em></span> comment in the PostScript
stream.</p></dd><dt><span class="term">%U</span></dt><dd><p>If authenticated printing<a class="indexterm" name="id2899975"></a> has been enabled then this will be substituted
with the user name of the printjob's originator.</p></dd><dt><span class="term">%J</span></dt><dd><p>will be substituted with the contents of the
<span class="emphasis"><em>%%Title:</em></span> comment of the PostScript
stream.</p></dd></dl></div><p>Using these wildcards, one can pass those parameters directly to
programs or implement small wrapper scripts to call the printing
system in question.</p></div><div class="sect3" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="papcupssupport"></a>Using direct CUPS support</h4></div></div><div></div></div><p>Starting with Netatalk 2.0, direct CUPS integration is
available. In this case, defining only a queue name as
<tt class="option">pr</tt> parameter won't invoke the SysV lpd daemon but
uses CUPS instead. Unless a specific PPD has been assigned using the
<tt class="option">pd</tt> switch, the PPD configured in CUPS will be used by
<span><b class="command">papd</b></span>, too.</p><p>There exists one special share named "cupsautoadd". If this is
present in papd.conf, then all available CUPS queues will be served
automagically using the parameters assigned to this global share. But
subsequent printer definitions can be used to override these global
settings for individual spoolers.</p></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="papclient"></a>Using AppleTalk printers</h3></div></div><div></div></div><p>Netatalk's <a href="papstatus.8.html"><span class="citerefentry"><span class="refentrytitle"><span><b class="command">papstatus</b></span></span>(8)</span></a> can be used to query AppleTalk printers, <a href="pap.1.html"><span class="citerefentry"><span class="refentrytitle"><span><b class="command">pap</b></span></span>(1)</span></a> to print to them. With <a href="psf.8.html"><span class="citerefentry"><span class="refentrytitle"><span><b class="command">psf</b></span></span>(8)</span></a> there exists a lpd filter program suitable for
converting other formats (like text) to PostScript output, do page
accounting<a class="indexterm" name="id2900144"></a> and eventually change the page order using <a href="psorder.1.html"><span class="citerefentry"><span class="refentrytitle"><span><b class="command">psorder</b></span></span>(1)</span></a>. But these days, modern printing systems like CUPS can
do the latter tasks for themselves in a more reliable way.</p><p><span><b class="command">pap</b></span> can be used stand-alone or as part of an
output filter or a CUPS backend<a class="indexterm" name="id2900186"></a> (which is the preferred method since one does not have to
deal with all the options).</p><div class="example"><a name="id2900203"></a><p class="title"><b>Example3.10.<span>pap</span> printing to a PostScript
LaserWriter</b></p><pre class="programlisting">pap -p"ColorLaserWriter 16/600@*" /usr/share/doc/gs/examples/tiger.ps</pre><p>
The file <tt class="filename">/usr/share/doc/gs/examples/tiger.ps</tt> is
sent to a printer called "ColorLaserWriter 16/600" in the standard
zone "*". The device type is "LaserWriter" (can be suppressed since it
is the default).</p></div><div class="example"><a name="id2900240"></a><p class="title"><b>Example3.11.<span>pap</span> printing to a non-PostScript
printer</b></p><pre class="programlisting">gs -q -dNOPAUSE -sDEVICE=cdjcolor -sOutputFile=- test.ps | pap -E</pre><p>GhostScript
is used to convert a PostScript job to PCL3 output suitable for a
Color DeskWriter. Since no file has been supplied on the command line,
<span><b class="command">pap</b></span> reads the data from stdin. The printer's
address will be read from the <tt class="filename">.paprc</tt> file in the
same directory, <span><b class="command">pap</b></span> will be called (in our example
simply containing "Color DeskWriter:DeskWriter@Printers"). The
<tt class="option">-E</tt> switch forces <span><b class="command">pap</b></span> to not wait
for an EOF from the printer.</p></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="timeservices"></a>Time Services<a class="indexterm" name="id2900317"></a><a class="indexterm" name="id2900327"></a></h2></div></div><div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="timelord"></a>Using Netatalk as a time server for Macintoshes</h3></div></div><div></div></div><p><span><b class="command">timelord</b></span><a class="indexterm" name="id2900361"></a>, an AppleTalk based time server, is deprecated these
days. Use NTP<a class="indexterm" name="id2900374"></a> instead.</p><p>For further information please have a look at the <a href="timelord.8.html"><span class="citerefentry"><span class="refentrytitle">timelord</span>(8)</span></a> manual page.</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2900410"></a>Starting and stopping Netatalk</h2></div></div><div></div></div><p>The Netatalk distribution comes with several operating system
specific startup script templates that are tailored according to the
options given to the "configure" script before compiling. Currently,
templates are provided for NetBSD, BSD, RedHat, SuSE and True64. You can
select to install the generated startup script(s)<a class="indexterm" name="id2900428"></a> by specifying a system type to "configure". To
automatically install startup scripts for e.g. the SuSE Linux distribution
try to give the <tt class="option">--enable-suse</tt> option to "configure". Some
of the scripts can be further parametrized by the configuration file
netatalk.conf (described in the <a href="netatalk.conf.5.html"><span class="citerefentry"><span class="refentrytitle">netatalk.conf</span>(5)</span></a> manual page), some obtain that information in another,
operating system specific way (like Netbsd).</p><p>Since new releases of Linux distributions appear all the time and
the startup procedure for the other systems mentioned above might change
as well, it is probably a good idea to not blindly install a startup
script but to look at it first to see if it will work on your system. If
you use Netatalk as part of a fixed setup, like a Linux distribution, an
RPM or a BSD package, things will probably have been arranged properly for
you. The following therefore applies mostly for people who have compiled
Netatalk themselves.</p><p>The following daemons need to be started by whatever startup script
mechanism is used:</p><div class="itemizedlist"><ul type="disc"><li><p>atalkd<a class="indexterm" name="id2900498"></a> (if you use the AppleTalk protocol)</p></li><li><p>afpd<a class="indexterm" name="id2900518"></a></p></li><li><p>cnid_metad<a class="indexterm" name="id2900537"></a> (if the dbd CNID backend is used)</p></li><li><p>papd<a class="indexterm" name="id2900557"></a> (if you want to provide print services via
AppleTalk)</p></li><li><p>timelord<a class="indexterm" name="id2900577"></a> (for old style time synchronisation via
AppleTalk)</p></li></ul></div><p>Additionally, make sure that the various configuration files
(<tt class="filename">afpd.conf</tt>,
<tt class="filename">AppleVolumes.default</tt>, <tt class="filename">papd.conf</tt>
etc.) are in the right place and that
<tt class="filename">netatalk.conf</tt><a class="indexterm" name="id2900624"></a> (if used) contains the right entries. If you want e.g. papd
to be started using this mechanism, set the environment variable
"<tt class="option">PAPD_RUN</tt>"<a class="indexterm" name="id2900642"></a> to "yes" in netatalk.conf. See the manual pages for
details.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="installation.html">Prev</a></td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"><a accesskey="n" href="upgrade.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter2.Installation</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">Chapter4.Upgrading from a previous version of Netatalk</td></tr></table></div></body></html>
|
