File: afp.conf.5.in

package info (click to toggle)
netatalk 3.1.12~ds-3
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 14,756 kB
  • sloc: ansic: 104,976; sh: 8,247; xml: 7,394; perl: 1,936; makefile: 1,430; python: 1,342; yacc: 309; lex: 49
file content (1526 lines) | stat: -rw-r--r-- 49,193 bytes parent folder | download | duplicates (2)
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
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
'\" t
.\"     Title: afp.conf
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.0 <http://docbook.sf.net/>
.\"      Date: 27 Dec 2016
.\"    Manual: @NETATALK_VERSION@
.\"    Source: @NETATALK_VERSION@
.\"  Language: English
.\"
.TH "AFP\&.CONF" "5" "27 Dec 2016" "@NETATALK_VERSION@" "@NETATALK_VERSION@"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
afp.conf \- Netatalk configuration file
.SH "SYNOPSIS"
.PP
The
afp\&.conf
file is the configuration file for the
\fBNetatalk\fR
AFP file server\&.
.PP
All AFP specific configuration and AFP volume definitions are done via this file\&.
.SH "FILE FORMAT"
.PP
The file consists of sections and parameters\&. A section begins with the name of the section in square brackets and continues until the next section begins\&. Sections contain parameters of the form:
.sp
.if n \{\
.RS 4
.\}
.nf
    \fIname\fR = \fIvalue \fR
    
.fi
.if n \{\
.RE
.\}
.PP
The file is line\-based \- that is, each newline\-terminated line represents either a comment, a section name or a parameter\&.
.PP
Section and parameter names are case sensitive\&.
.PP
Only the first equals sign in a parameter is significant\&. Whitespace before or after the first equals sign is discarded\&. Leading, trailing and internal whitespace in section and parameter names is irrelevant\&. Leading and trailing whitespace in a parameter value is discarded\&. Internal whitespace within a parameter value is retained verbatim\&.
.PP
Any line beginning with a semicolon (\(lq;\(rq) or a hash (\(lq#\(rq) character is ignored, as are lines containing only whitespace\&.
.PP
Any line ending in a
\(lq \e \(rq
is continued on the next line in the customary UNIX fashion\&.
.PP
The values following the equals sign in parameters are all either a string (no quotes needed) or a boolean, which may be given as yes/no, 1/0 or true/false\&. Case is not significant in boolean values, but is preserved in string values\&. Some items such as "file perm"s are numeric\&.
.PP
The parameter
\fBinclude = \fR\fB\fIpath\fR\fR
allows you to include one config file inside another\&. The file is included literally, as though typed in place\&. Nested includes are not supported\&.
.SH "SECTION DESCRIPTIONS"
.PP
Each section in the configuration file (except for the [Global] section) describes a shared resource (known as a
\(lqvolume\(rq)\&. The section name is the name of the volume and the parameters within the section define the volume attributes and options\&.
.PP
There are two special sections, [Global] and [Homes], which are described under
\fIspecial sections\fR\&. The following notes apply to ordinary section descriptions\&.
.PP
A volume consists of a directory to which access is being given plus a description of the access rights which are granted to the user of the service\&. For volumes the
\fBpath\fR
option must specify the directory to share\&.
.PP
Any volume section without
\fBpath\fR
option is considered a
\fIvol preset\fR
which can be selected in other volume sections via the
\fBvol preset\fR
option and constitutes defaults for the volume\&. For any option specified both in a preset
\fIand\fR
in a volume section the volume section setting completely substitutes the preset option\&.
.PP
The access rights granted by the server are masked by the access rights granted to the specified or guest UNIX user by the host system\&. The server does not grant more access than the host system grants\&.
.PP
The following sample section defines an AFP volume\&. The user has full access to the path
/foo/bar\&. The share is accessed via the share name
baz:
.sp
.if n \{\
.RS 4
.\}
.nf
 [baz]
    path = /foo/bar 
.fi
.if n \{\
.RE
.\}
.SH "SPECIAL SECTIONS"
.SS "The [Global] section"
.PP
Parameters in this section apply to the server as a whole\&. Parameters denoted by a (G) below are must be set in this section\&.
.SS "The [Homes] section"
.PP
This section enable sharing of the UNIX server user home directories\&. Specifying an optional
\fBpath\fR
parameter means that not the whole user home will be shared but the subdirectory
\fBpath\fR\&. It is necessary to define the
\fBbasedir regex\fR
option\&. It should be a regex which matches the parent directory of the user homes\&. Parameters denoted by a (H) belong to volume sections\&. The optional parameter
\fBhome name\fR
can be used to change the AFP volume name which
\fI$u\*(Aqs home\fR
by default\&. See below under VARIABLE SUBSTITUTIONS\&.
.PP
The following example illustrates this\&. Given all user home directories are stored under
/home:
.sp
.if n \{\
.RS 4
.\}
.nf
 [Homes]
      path = afp\-data
      basedir regex = /home
.fi
.if n \{\
.RE
.\}
.sp
For a user
\fIjohn\fR
this results in an AFP home volume with a path of
/home/john/afp\-data\&.
.PP
If
\fBbasedir regex\fR
contains symlink, set the canonicalized absolute path\&. When
/home
links to
/usr/home:
.sp
.if n \{\
.RS 4
.\}
.nf
 [Homes]
      basedir regex = /usr/home
.fi
.if n \{\
.RE
.\}
.SH "PARAMETERS"
.PP
Parameters define the specific attributes of sections\&.
.PP
Some parameters are specific to the [Global] section (e\&.g\&.,
\fIlog type\fR)\&. All others are permissible only in volume sections\&. The letter
\fIG\fR
in parentheses indicates that a parameter is specific to the [Global] section\&. The letter
\fIV\fR
indicates that a parameter can be specified in a volume specific section\&.
.SH "VARIABLE SUBSTITUTIONS"
.PP
You can use variables in volume names\&. The use of variables in paths is limited to $u\&.
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
if you specify an unknown variable, it will not get converted\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
if you specify a known variable, but that variable doesn\*(Aqt have a value, it will get ignored\&.
.RE
.PP
The variables which can be used for substitutions are:
.PP
$b
.RS 4
basename
.RE
.PP
$c
.RS 4
client\*(Aqs ip address
.RE
.PP
$d
.RS 4
volume pathname on server
.RE
.PP
$f
.RS 4
full name (contents of the gecos field in the passwd file)
.RE
.PP
$g
.RS 4
group name
.RE
.PP
$h
.RS 4
hostname
.RE
.PP
$i
.RS 4
client\*(Aqs ip, without port
.RE
.PP
$s
.RS 4
server name (this can be the hostname)
.RE
.PP
$u
.RS 4
user name (if guest, it is the user that guest is running as)
.RE
.PP
$v
.RS 4
volume name
.RE
.PP
$$
.RS 4
prints dollar sign ($)
.RE
.SH "EXPLANATION OF GLOBAL PARAMETERS"
.SS "Authentication Options"
.PP
ad domain = \fIDOMAIN\fR \fB(G)\fR
.RS 4
Append @DOMAIN to username when authenticating\&. Useful in Active Directory environments that otherwise would require the user to enter the full user@domain string\&.
.RE
.PP
admin auth user = \fIuser\fR \fB(G)\fR
.RS 4
Specifying e\%.g\&. "\fBadmin auth user = root\fR" whenever a normal user login fails, afpd will try to authenticate as the specified
\fBadmin auth user\fR\&. If this succeeds, a normal session is created for the original connecting user\&. Said differently: if you know the password of
\fBadmin auth user\fR, you can authenticate as any other user\&.
.RE
.PP
admin group = \fIgroup\fR \fB(G)\fR
.RS 4
Allows users of a certain group to be seen as the superuser when they log in\&. This option is disabled by default\&.
.RE
.PP
force user = \fIUSER\fR \fB(G)\fR
.RS 4
This specifies a UNIX user name that will be assigned as the default user for all users connecting to this server\&. This is useful for sharing files\&. You should also use it carefully as using it incorrectly can cause security problems\&.
.RE
.PP
force group = \fIGROUP\fR \fB(G)\fR
.RS 4
This specifies a UNIX group name that will be assigned as the default primary group for all users connecting to this server\&.
.RE
.PP
k5 keytab = \fIpath\fR \fB(G)\fR, k5 service = \fIservice\fR \fB(G)\fR, k5 realm = \fIrealm\fR \fB(G)\fR
.RS 4
These are required if the server supports the Kerberos 5 authentication UAM\&.
.RE
.PP
nt domain = \fIDOMAIN\fR \fB(G)\fR, nt separator = \fISEPARATOR\fR \fB(G)\fR
.RS 4
Use for e\&.g\&. winbind authentication, prepends both strings before the username from login and then tries to authenticate with the result through the available and active UAM authentication modules\&.
.RE
.PP
save password = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(G)\fR
.RS 4
Enables or disables the ability of clients to save passwords locally\&.
.RE
.PP
set password = \fIBOOLEAN\fR (default: \fIno\fR) \fB(G)\fR
.RS 4
Enables or disables the ability of clients to change their passwords via chooser or the "connect to server" dialog\&.
.RE
.PP
uam list = \fIuam list\fR \fB(G)\fR
.RS 4
Space or comma separated list of UAMs\&. (The default is "uams_dhx\&.so uams_dhx2\&.so")\&.
.sp
The most commonly used UAMs are:
.PP
uams_guest\&.so
.RS 4
allows guest logins
.RE
.PP
uams_clrtxt\&.so
.RS 4
(uams_pam\&.so or uams_passwd\&.so) Allow logins with passwords transmitted in the clear\&. (legacy)
.RE
.PP
uams_randnum\&.so
.RS 4
allows Random Number and Two\-Way Random Number Exchange for authentication (requires a separate file containing the passwords, either @pkgconfdir@/afppasswd file or the one specified via "\fBpasswd file\fR")\&. See
\fBafppasswd\fR(1)
for details\&. (legacy)
.RE
.PP
uams_dhx\&.so
.RS 4
(uams_dhx_pam\&.so or uams_dhx_passwd\&.so) Allow Diffie\-Hellman eXchange (DHX) for authentication\&.
.RE
.PP
uams_dhx2\&.so
.RS 4
(uams_dhx2_pam\&.so or uams_dhx2_passwd\&.so) Allow Diffie\-Hellman eXchange 2 (DHX2) for authentication\&.
.RE
.PP
uam_gss\&.so
.RS 4
Allow Kerberos V for authentication (optional)
.RE
.RE
.PP
uam path = \fIpath\fR \fB(G)\fR
.RS 4
Sets the default path for UAMs for this server (default is @libdir@/netatalk)\&.
.RE
.SS "Charset Options"
.PP
With OS X Apple introduced the AFP3 protocol\&. One of the big changes was, that AFP3 uses Unicode names encoded as Decomposed UTF\-8 (UTF8\-MAC)\&. Previous AFP/OS versions used charsets like MacRoman, MacCentralEurope, etc\&.
.PP
To be able to serve AFP3 and older clients at the same time,
\fBafpd\fR
needs to be able to convert between UTF\-8 and Mac charsets\&. Even OS X clients partly still rely on the mac charset\&. As there\*(Aqs no way,
\fBafpd\fR
can detect the codepage a pre AFP3 client uses, you have to specify it using the
\fBmac charset\fR
option\&. The default is MacRoman, which should be fine for most western users\&.
.PP
As
\fBafpd\fR
needs to interact with UNIX operating system as well, it needs to be able to convert from UTF8\-MAC / Mac charset to the UNIX charset\&. By default
\fBafpd\fR
uses
\fIUTF8\fR\&. You can set the UNIX charset using the
\fBunix charset\fR
option\&. If you\*(Aqre using extended characters in the configuration files for
\fBafpd\fR, make sure your terminal matches the
\fBunix charset\fR\&.
.PP
mac charset = \fICHARSET\fR \fB(G)/(V)\fR
.RS 4
Specifies the Mac clients charset, e\&.g\&.
\fIMAC_ROMAN\fR\&. This is used to convert strings and filenames to the clients codepage for OS9 and Classic, i\&.e\&. for authentication and AFP messages (SIGUSR2 messaging)\&. This will also be the default for the volumes
\fBmac charset\fR\&. Defaults to
\fIMAC_ROMAN\fR\&.
.RE
.PP
unix charset = \fICHARSET\fR \fB(G)\fR
.RS 4
Specifies the servers unix charset, e\&.g\&.
\fIISO\-8859\-15\fR
or
\fIEUC\-JP\fR\&. This is used to convert strings to/from the systems locale, e\&.g\&. for authentication, server messages and volume names\&. If
\fILOCALE\fR
is set, the systems locale is used\&. Defaults to
\fIUTF8\fR\&.
.RE
.PP
vol charset = \fICHARSET\fR \fB(G)/(V)\fR
.RS 4
Specifies the encoding of the volumes filesystem\&. By default, it is the same as
\fBunix charset\fR\&.
.RE
.SS "Password Options"
.PP
passwd file = \fIpath\fR \fB(G)\fR
.RS 4
Sets the path to the Randnum UAM passwd file for this server (default is @pkgconfdir@/afppasswd)\&.
.RE
.PP
passwd minlen = \fInumber\fR \fB(G)\fR
.RS 4
Sets the minimum password length, if supported by the UAM
.RE
.SS "Network Options"
.PP
advertise ssh = \fIBOOLEAN\fR (default: \fIno\fR) \fB(G)\fR
.RS 4
Allows old Mac OS X clients (10\&.3\&.3\-10\&.4) to automagically establish a tunneled AFP connection through SSH\&. If this option is set, the server\*(Aqs answers to client\*(Aqs FPGetSrvrInfo requests contain an additional entry\&. It depends on both client\*(Aqs settings and a correctly configured and running
\fBsshd\fR(8)
on the server to let things work\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
Setting this option is not recommended since globally encrypting AFP connections via SSH will increase the server\*(Aqs load significantly\&. On the other hand, Apple\*(Aqs client side implementation of this feature in MacOS X versions prior to 10\&.3\&.4 contained a security flaw\&.
.sp .5v
.RE
.RE
.PP
afp interfaces = \fIname [name \&.\&.\&.]\fR \fB(G)\fR
.RS 4
Specifies the network interfaces that the server should listens on\&. The default is advertise the first IP address of the system, but to listen for any incoming request\&.
.RE
.PP
afp listen = \fIip address[:port] [ip address[:port] \&.\&.\&.]\fR \fB(G)\fR
.RS 4
Specifies the IP address that the server should advertise
\fBand\fR
listens to\&. The default is advertise the first IP address of the system, but to listen for any incoming request\&. The network address may be specified either in dotted\-decimal format for IPv4 or in hexadecimal format for IPv6\&.
.sp
IPv6 address + port combination must use URL the format using square brackets [IPv6]:port
.RE
.PP
afp port = \fIport number\fR \fB(G)\fR
.RS 4
Allows a different TCP port to be used for AFP\&. The default is 548\&. Also sets the default port applied when none specified in an
\fBafp listen\fR
option\&.
.RE
.PP
cnid listen = \fIip address[:port] [ip address[:port] \&.\&.\&.]\fR \fB(G)\fR
.RS 4
Specifies the IP address that the CNID server should listen on\&. The default is
\fBlocalhost:4700\fR\&.
.RE
.PP
disconnect time = \fInumber\fR \fB(G)\fR
.RS 4
Keep disconnected AFP sessions for
\fInumber\fR
hours before dropping them\&. Default is 24 hours\&.
.RE
.PP
dsireadbuf = \fInumber\fR \fB(G)\fR
.RS 4
Scale factor that determines the size of the DSI/TCP readahead buffer, default is 12\&. This is multiplies with the DSI server quantum (default 1MiB) to give the size of the buffer\&. Increasing this value might increase throughput in fast local networks for volume to volume copies\&.
\fINote\fR: This buffer is allocated per afpd child process, so specifying large values will eat up large amount of memory (buffer size * number of clients)\&.
.RE
.PP
fqdn = \fIname[:port]\fR \fB(G)\fR
.RS 4
Specifies a fully\-qualified domain name, with an optional port\&. This is discarded if the server cannot resolve it\&. This option is not honored by AppleShare clients <= 3\&.8\&.3\&. This option is disabled by default\&. Use with caution as this will involve a second name resolution step on the client side\&. Also note that afpd will advertise this name:port combination but not automatically listen to it\&.
.RE
.PP
hostname = \fIname\fR \fB(G)\fR
.RS 4
Use this instead of the result from calling hostname for determining which IP address to advertise, therefore the hostname is resolved to an IP which is the advertised\&. This is NOT used for listening and it is also overwritten by
\fBafp listen\fR\&.
.RE
.PP
max connections = \fInumber\fR \fB(G)\fR
.RS 4
Sets the maximum number of clients that can simultaneously connect to the server (default is 200)\&.
.RE
.PP
server quantum = \fInumber\fR \fB(G)\fR
.RS 4
This specifies the DSI server quantum\&. The default value is 0x100000 (1 MiB)\&. The maximum value is 0xFFFFFFFFF, the minimum is 32000\&. If you specify a value that is out of range, the default value will be set\&. Do not change this value unless you\*(Aqre absolutely sure, what you\*(Aqre doing
.RE
.PP
sleep time = \fInumber\fR \fB(G)\fR
.RS 4
Keep sleeping AFP sessions for
\fInumber\fR
hours before disconnecting clients in sleep mode\&. Default is 10 hours\&.
.RE
.PP
tcprcvbuf = \fInumber\fR \fB(G)\fR
.RS 4
Try to set TCP receive buffer using setsockopt()\&. Often OSes impose restrictions on the applications ability to set this value\&.
.RE
.PP
tcpsndbuf = \fInumber\fR \fB(G)\fR
.RS 4
Try to set TCP send buffer using setsockopt()\&. Often OSes impose restrictions on the applications ability to set this value\&.
.RE
.PP
recvfile = \fIBOOLEAN\fR (default: \fIno\fR) \fB(G)\fR
.RS 4
Whether to use splice() on Linux for receiving data\&.
.RE
.PP
splice size = \fInumber\fR (default: \fI64k\fR) \fB(G)\fR
.RS 4
Maximum number of bytes spliced\&.
.RE
.PP
use sendfile = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(G)\fR
.RS 4
Whether to use sendfile.\" sendfile
syscall for sending file data to clients\&.
.RE
.PP
zeroconf = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(G)\fR
.RS 4
Whether to use automatic Zeroconf.\" Zeroconf: Bonjour
service registration if Avahi or mDNSResponder were compiled in\&.
.RE
.SS "Miscellaneous Options"
.PP
afp read locks = \fIBOOLEAN\fR (default: \fIno\fR) \fB(G)\fR
.RS 4
Whether to apply locks to the byte region read in FPRead calls\&. The AFP spec mandates this, but it\*(Aqs not really in line with UNIX semantics and is a performance hug\&.
.RE
.PP
afpstats = \fIBOOLEAN\fR (default: \fIno\fR) \fB(G)\fR
.RS 4
Whether to provide AFP runtime statistics (connected users, open volumes) via dbus\&.
.RE
.PP
basedir regex = \fIregex\fR \fB(H)\fR
.RS 4
Regular expression which matches the parent directory of the user homes\&. If
\fBbasedir regex\fR
contains symlink, you must set the canonicalized absolute path\&. In the simple case this is just a path i\&.e\&.
\fBbasedir regex = /home\fR
.RE
.PP
chmod request = \fIpreserve (default) | ignore | simple\fR \fB(G)/(V)\fR
.RS 4
Advanced permission control that deals with ACLs\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBignore\fR
\- UNIX chmod() requests are completely ignored, use this option to allow the parent directory\*(Aqs ACL inheritance full control over new items\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBpreserve\fR
\- preserve ZFS ACEs for named users and groups or POSIX ACL group mask
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}

\fBsimple\fR
\- just to a chmod() as requested without any extra steps
.RE
.RE
.PP
close vol = \fIBOOLEAN\fR (default: \fIno\fR) \fB(G)\fR
.RS 4
Whether to close volumes possibly opened by clients when they\*(Aqre removed from the configuration and the configuration is reloaded\&.
.RE
.PP
cnid mysql host = \fIMySQL server address\fR \fB(G)\fR
.RS 4
name or address of a MySQL server for use with the mysql CNID backend\&.
.RE
.PP
cnid mysql user = \fIMySQL user\fR \fB(G)\fR
.RS 4
MySQL user for authentication with the server\&.
.RE
.PP
cnid mysql pw = \fIpassword\fR \fB(G)\fR
.RS 4
Password for MySQL server\&.
.RE
.PP
cnid mysql db = \fIdatabase name\fR \fB(G)\fR
.RS 4
Name of an existing database for which the specified user has full privileges\&.
.RE
.PP
cnid server = \fIipaddress[:port]\fR \fB(G)/(V)\fR
.RS 4
Specifies the IP address and port of a cnid_metad server, required for CNID dbd backend\&. Defaults to localhost:4700\&. The network address may be specified either in dotted\-decimal format for IPv4 or in hexadecimal format for IPv6\&.\-
.RE
.PP
dbus daemon = \fIpath\fR \fB(G)\fR
.RS 4
Sets the path to dbus\-daemon binary used by Spotlight feature\&. The default value
[@DBUS_DAEMON_PATH@]
is determined when building netatalk\&.
.RE
.PP
dircachesize = \fInumber\fR \fB(G)\fR
.RS 4
Maximum possible entries in the directory cache\&. The cache stores directories and files\&. It is used to cache the full path to directories and CNIDs which considerably speeds up directory enumeration\&.
.sp
Default size is 8192, maximum size is 131072\&. Given value is rounded up to nearest power of 2\&. Each entry takes about 100 bytes, which is not much, but remember that every afpd child process for every connected user has its cache\&.
.RE
.PP
extmap file = \fIpath\fR \fB(G)\fR
.RS 4
Sets the path to the file which defines file extension type/creator mappings\&. (default is @pkgconfdir@/extmap\&.conf)\&.
.RE
.PP
force xattr with sticky bit = \fIBOOLEAN\fR (default: \fIno\fR) \fB(G/V)\fR
.RS 4
Writing metadata xattr on directories with the sticky bit set may fail even though we may have write access to a directory, because if the sticky bit is set only the owner is allowed to write xattrs\&.
.sp
By enabling this option Netatalk will write the metadata xattr as root\&.
.RE
.PP
guest account = \fIname\fR \fB(G)\fR
.RS 4
Specifies the user that guests should use (default is "nobody")\&. The name should be quoted\&.
.RE
.PP
home name = \fIname\fR \fB(H)\fR
.RS 4
AFP user home volume name\&. The default is
\fI$u\*(Aqs home\fR\&.
.RE
.PP
ignored attributes = \fIall | nowrite | nodelete | norename\fR \fB(G)/(V)\fR
.RS 4
Speficy a set of file and directory attributes that shall be ignored by the server,
\fBall\fR
includes all the other options\&.
.sp
In OS X when the Finder sets a lock on a file/directory or you set the BSD uchg flag in the Terminal, all three attributes are used\&. Thus in order to ignore the Finder lock/BSD uchg flag, add set
\fIignored attributes = all\fR\&.
.RE
.PP
login message = \fImessage\fR \fB(G)/(V)\fR
.RS 4
Sets a message to be displayed when clients logon to the server\&. The message should be in
\fBunix charset\fR
and should be quoted\&. Extended characters are allowed\&.
.RE
.PP
mimic model = \fImodel\fR \fB(G)\fR
.RS 4
Specifies the icon model that appears on clients\&. Defaults to off\&. Note that netatalk must support Zeroconf\&. Examples: RackMac (same as Xserve), PowerBook, PowerMac, Macmini, iMac, MacBook, MacBookPro, MacBookAir, MacPro, AppleTV1,1, AirPort\&.
.RE
.PP
signature = <text> \fB(G)\fR
.RS 4
Specify a server signature\&. The maximum length is 16 characters\&. This option is useful for clustered environments, to provide fault isolation etc\&. By default, afpd generate signature and saving it to
@localstatedir@/netatalk/afp_signature\&.conf
automatically (based on random number)\&. See also asip\-status\&.pl(1)\&.
.RE
.PP
solaris share reservations = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(G)\fR
.RS 4
Use share reservations on Solaris\&. Solaris CIFS server uses this too, so this makes a lock coherent multi protocol server\&.
.RE
.PP
sparql results limit = \fINUMBER\fR (default: \fIUNLIMITED\fR) \fB(G)\fR
.RS 4
Impose a limit on the number of results queried from Tracker via SPARQL queries\&.
.RE
.PP
spotlight = \fIBOOLEAN\fR (default: \fIno\fR) \fB(G)/(V)\fR
.RS 4
Whether to enable Spotlight searches\&. Note: once the global option is enabled, any volume that is not enabled won\*(Aqt be searchable at all\&. See also
\fIdbus daemon\fR
option\&.
.RE
.PP
spotlight attributes = \fICOMMA SEPARATED STRING\fR (default: \fIEMPTY\fR) \fB(G)\fR
.RS 4
A list of attributes that are allowed to be used in Spotlight searches\&. By default all attributes can be searched, passing a string limits attributes to elements of the string\&. Example:
.sp
.if n \{\
.RS 4
.\}
.nf
spotlight attributes = *,kMDItemTextContent
.fi
.if n \{\
.RE
.\}
.RE
.PP
spotlight expr = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(G)\fR
.RS 4
Whether to allow the use of logic expression in searches\&.
.RE
.PP
start dbus = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(G)\fR
.RS 4
Whether to start a dbus instance for use with Tracker\&.
.RE
.PP
start tracker = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(G)\fR
.RS 4
Whether to start Tracker with "\fBtracker daemon \-s\fR"\&. In case of old Tracker, "\fBtracker\-control \-s\fR" is used instead\&.
.RE
.PP
veto message = \fIBOOLEAN\fR (default: \fIno\fR) \fB(G)\fR
.RS 4
Send optional AFP messages for vetoed files\&. Then whenever a client tries to access any file or directory with a vetoed name, it will be sent an AFP message indicating the name and the directory\&.
.RE
.PP
vol dbpath = \fIpath\fR \fB(G)/(V)\fR
.RS 4
Sets the database information to be stored in path\&. You have to specify a writable location, even if the volume is read only\&. The default is
@localstatedir@/netatalk/CNID/$v/\&.
.RE
.PP
vol dbnest = \fIBOOLEAN\fR (default: \fIno\fR) \fB(G)\fR
.RS 4
Setting this option to true brings back Netatalk 2 behaviour of storing the CNID database in a folder called \&.AppleDB inside the volume root of each share\&.
.RE
.PP
volnamelen = \fInumber\fR \fB(G)\fR
.RS 4
Max length of UTF8\-MAC volume name for Mac OS X\&. Note that Hangul is especially sensitive to this\&.
.sp
.if n \{\
.RS 4
.\}
.nf
73: limit of Mac OS X 10\&.1
80: limit of Mac OS X 10\&.4/10\&.5 (default)
255: limit of recent Mac OS X
.fi
.if n \{\
.RE
.\}
.sp
Mac OS 9 and earlier are not influenced by this, because Maccharset volume name is always limited to 27 bytes\&.
.RE
.PP
vol preset = \fIname\fR \fB(G)/(V)\fR
.RS 4
Use section
\fBname\fR
as option preset for all volumes (when set in the [Global] section) or for one volume (when set in that volume\*(Aqs section)\&.
.RE
.PP
zeroconf name = \fIname\fR \fB(G)\fR
.RS 4
Specifies a human\-readable name that uniquely describes registered services\&. The zeroconf name is advertised as UTF\-8, up to 63 octets (bytes) in length\&. Defaults to hostname\&. Note that netatalk must support Zeroconf\&.
.RE
.SS "Logging Options"
.PP
log file = \fIlogfile\fR \fB(G)\fR
.RS 4
If not specified Netatalk logs to syslogs daemon facility\&. Otherwise it logs to
\fBlogfile\fR\&.
.RE
.PP
log level = \fItype:level [type:level \&.\&.\&.]\fR \fB(G)\fR, log level = \fItype:level,[type:level, \&.\&.\&.]\fR \fB(G)\fR
.RS 4
Specify that any message of a loglevel up to the given
\fBlog level\fR
should be logged\&.
.sp
By default afpd logs to syslog with a default logging setup equivalent to
\fBdefault:note\fR
.sp
logtypes: default, afpdaemon, logger, uamsdaemon
.sp
loglevels: severe, error, warn, note, info, debug, debug6, debug7, debug8, debug9, maxdebug
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
Both logtype and loglevels are case insensitive\&.
.sp .5v
.RE
.RE
.SS "Filesystem Change Events (FCE.\" FCE )"
.PP
Netatalk includes a nifty filesystem change event mechanism where afpd processes notify interested listeners about certain filesystem event by UDP network datagrams\&.
.PP
The following FCE events are defined:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
file modification (\fBfmod\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
file deletion (\fBfdel\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
directory deletion (\fBddel\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
file creation (\fBfcre\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
directory creation (\fBdcre\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
file move or rename (\fBfmov\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
directory move or rename (\fBdmov\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
login (\fBlogin\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
logout (\fBlogout\fR)
.RE
.PP
fce listener = \fIhost[:port]\fR \fB(G)\fR
.RS 4
Enables sending FCE events to the specified
\fIhost\fR, default
\fIport\fR
is 12250 if not specified\&. Specifying multiple listeners is done by having this option once for each of them\&.
.RE
.PP
fce version = \fI1|2\fR \fB(G)\fR
.RS 4
FCE protocol version, default is 1\&. You need version 2 for the fmov, dmov, login or logout events\&.
.RE
.PP
fce events = \fIfmod,fdel,ddel,fcre,dcre,fmov,dmov,login,logout\fR \fB(G)\fR
.RS 4
Specifies which FCE events are active, default is
\fIfmod,fdel,ddel,fcre,dcre\fR\&.
.RE
.PP
fce coalesce = \fIall|delete|create\fR \fB(G)\fR
.RS 4
Coalesce FCE events\&.
.RE
.PP
fce holdfmod = \fIseconds\fR \fB(G)\fR
.RS 4
This determines the time delay in seconds which is always waited if another file modification for the same file is done by a client before sending an FCE file modification event (fmod)\&. For example saving a file in Photoshop would generate multiple events by itself because the application is opening, modifying and closing a file multiple times for every "save"\&. Default: 60 seconds\&.
.RE
.PP
fce ignore names = \fINAME[/NAME2/\&.\&.\&.]\fR \fB(G)\fR
.RS 4
Slash delimited list of filenames for which FCE events shall not be generated\&. Default: \&.DS_Store\&.
.RE
.PP
fce notify script = \fIPATH\fR \fB(G)\fR
.RS 4
Script which will be executed for every FCE event, see contrib/shell_utils/fce_ev_script\&.sh from the Netatalk sources for an example script\&.
.RE
.SS "Debug Parameters"
.PP
These options are useful for debugging only\&.
.PP
tickleval = \fInumber\fR \fB(G)\fR
.RS 4
Sets the tickle timeout interval (in seconds)\&. Defaults to 30\&.
.RE
.PP
timeout = \fInumber\fR \fB(G)\fR
.RS 4
Specify the number of tickles to send before timing out a connection\&. The default is 4, therefore a connection will timeout after 2 minutes\&.
.RE
.PP
client polling = \fIBOOLEAN\fR (default: \fIno\fR) \fB(G)\fR
.RS 4
With this option enabled, afpd won\*(Aqt advertise that it is capable of server notifications, so that connected clients poll the server every 10 seconds to detect changes in opened server windows\&.
\fINote\fR: Depending on the number of simultaneously connected clients and the network\*(Aqs speed, this can lead to a significant higher load on your network!
.sp
Do not use this option any longer as present Netatalk correctly supports server notifications, allowing connected clients to update folder listings in case another client changed the contents\&.
.RE
.SS "Options for ACL handling"
.PP
By default, the effective permission of the authenticated user are only mapped to the mentioned UARights permission structure, not the UNIX mode\&. You can adjust this behaviour with the configuration option
\fBmap acls\fR:
.PP
map acls = \fInone|rights|mode\fR \fB(G)\fR
.RS 4
.PP
none
.RS 4
no mapping of ACLs
.RE
.PP
rights
.RS 4
effective permissions are mapped to UARights structure\&. This is the default\&.
.RE
.PP
mode
.RS 4
ACLs are additionally mapped to the UNIX mode of the filesystem object\&.
.RE
.RE
.PP
If you want to be able to display ACLs on the client, you must setup both client and server as part on a authentication domain (directory service, e\&.g\&. LDAP, Open Directory, Active Directory)\&. The reason is, in OS X ACLs are bound to UUIDs, not just uid\*(Aqs or gid\*(Aqs\&. Therefor Netatalk must be able to map every filesystem uid and gid to a UUID so that it can return the server side ACLs which are bound to UNIX uid and gid mapped to OS X UUIDs\&.
.PP
Netatalk can query a directory server using LDAP queries\&. Either the directory server already provides an UUID attribute for user and groups (Active Directory, Open Directory) or you reuse an unused attribute (or add a new one) to you directory server (eg OpenLDAP)\&.
.PP
The following LDAP options must be configured for Netatalk:
.PP
ldap auth method = \fInone|simple|sasl\fR \fB(G)\fR
.RS 4
Authentication method:
\fBnone | simple | sasl\fR
.PP
none
.RS 4
anonymous LDAP bind
.RE
.PP
simple
.RS 4
simple LDAP bind
.RE
.PP
sasl
.RS 4
SASL\&. Not yet supported !
.RE
.RE
.PP
ldap auth dn = \fIdn\fR \fB(G)\fR
.RS 4
Distinguished Name of the user for simple bind\&.
.RE
.PP
ldap auth pw = \fIpassword\fR \fB(G)\fR
.RS 4
Password for simple bind\&.
.RE
.PP
ldap server = \fIhost\fR \fB(G)\fR
.RS 4
Name or IP address of your LDAP Server\&. This is only needed for explicit ACL support in order to be able to query LDAP for UUIDs\&.
.sp
You can use
\fBafpldaptest\fR(1)
to syntactically check your config\&.
.RE
.PP
ldap userbase = \fIbase dn\fR \fB(G)\fR
.RS 4
DN of the user container in LDAP\&.
.RE
.PP
ldap userscope = \fIscope\fR \fB(G)\fR
.RS 4
Search scope for user search:
\fBbase | one | sub\fR
.RE
.PP
ldap groupbase = \fIbase dn\fR \fB(G)\fR
.RS 4
DN of the group container in LDAP\&.
.RE
.PP
ldap groupscope = \fIscope\fR \fB(G)\fR
.RS 4
Search scope for group search:
\fBbase | one | sub\fR
.RE
.PP
ldap uuid attr = \fIdn\fR \fB(G)\fR
.RS 4
Name of the LDAP attribute with the UUIDs\&.
.sp
Note: this is used both for users and groups\&.
.RE
.PP
ldap name attr = \fIdn\fR \fB(G)\fR
.RS 4
Name of the LDAP attribute with the users short name\&.
.RE
.PP
ldap group attr = \fIdn\fR \fB(G)\fR
.RS 4
Name of the LDAP attribute with the groups short name\&.
.RE
.PP
ldap uuid string = \fISTRING\fR \fB(G)\fR
.RS 4
Format of the uuid string in the directory\&. A series of x and \-, where every x denotes a value 0\-9a\-f and every \- is a separator\&.
.sp
Default: xxxxxxxx\-xxxx\-xxxx\-xxxx\-xxxxxxxxxxxx
.RE
.PP
ldap uuid encoding = \fIstring | ms\-guid (default: string)\fR \fB(G)\fR
.RS 4
Format of the UUID of the LDAP attribute, allows usage of the binary objectGUID fields from Active Directory\&. If left unspecified, string is the default, which passes through the ASCII UUID returned by most other LDAP stores\&. If set to ms\-guid, the internal UUID representation is converted to and from the binary format used in the objectGUID attribute found on objects in Active Directory when interacting with the server\&.
.sp
See also the options
\fBldap user filter\fR
and
\fBldap group filter\fR\&.
.PP
string
.RS 4
UUID is a string, use with e\&.g\&. OpenDirectory\&.
.RE
.PP
ms\-guid
.RS 4
Binary objectGUID from Active Directory
.RE
.RE
.PP
ldap user filter = \fISTRING (default: unused)\fR \fB(G)\fR
.RS 4
Optional LDAP filter that matches user objects\&. This is necessary for Active Directory environments where users and groups are stored in the same directory subtree\&.
.sp
Recommended setting for Active Directory:
\fIobjectClass=user\fR\&.
.RE
.PP
ldap group filter = \fISTRING (default: unused)\fR \fB(G)\fR
.RS 4
Optional LDAP filter that matches group objects\&. This is necessary for Active Directory environments where users and groups are stored in the same directory subtree\&.
.sp
Recommended setting for Active Directory:
\fIobjectClass=group\fR\&.
.RE
.SH "EXPLANATION OF VOLUME PARAMETERS"
.SS "Parameters"
.PP
The section name defines the volume name\&. No two volumes may have the same name\&. The volume name cannot contain the
\*(Aq:\*(Aq
character\&. The volume name is mangled if it is very long\&. Mac charset volume name is limited to 27 characters\&. UTF8\-MAC volume name is limited to volnamelen parameter\&.
.PP
path = \fIPATH\fR \fB(V)\fR
.RS 4
The path name must be a fully qualified path name\&.
.RE
.PP
appledouble = \fIea|v2\fR \fB(V)\fR
.RS 4
Specify the format of the metadata files, which are used for saving Mac resource fork as well\&. Earlier versions used AppleDouble v2, the new default format is
\fBea\fR\&.
.RE
.PP
vol size limit = \fIsize in MiB\fR \fB(V)\fR
.RS 4
Useful for Time Machine: limits the reported volume size, thus preventing Time Machine from using the whole real disk space for backup\&. Example: "vol size limit = 1000" would limit the reported disk space to 1 GB\&.
\fBIMPORTANT: \fR
This is an approximated calculation taking into account the contents of Time Machine sparsebundle images\&. Therefor you MUST NOT use this volume to store other content when using this option, because it would NOT be accounted\&. The calculation works by reading the band size from the Info\&.plist XML file of the sparsebundle, reading the bands/ directory counting the number of band files, and then multiplying one with the other\&.
.RE
.PP
valid users = \fIuser @group\fR \fB(V)\fR
.RS 4
The allow option allows the users and groups that access a share to be specified\&. Users and groups are specified, delimited by spaces or commas\&. Groups are designated by a @ prefix\&. Names may be quoted in order to allow for spaces in names\&. Example:
.sp
.if n \{\
.RS 4
.\}
.nf
valid users = user "user 2" @group \(lq@group 2"
.fi
.if n \{\
.RE
.\}
.RE
.PP
invalid users = \fIusers/groups\fR \fB(V)\fR
.RS 4
The deny option specifies users and groups who are not allowed access to the share\&. It follows the same format as the "valid users" option\&.
.RE
.PP
hosts allow = \fIIP host address/IP netmask bits [ \&.\&.\&. ]\fR \fB(V)\fR
.RS 4
Only listed hosts and networks are allowed, all others are rejected\&. The network address may be specified either in dotted\-decimal format for IPv4 or in hexadecimal format for IPv6\&.
.sp
Example: hosts allow = 10\&.1\&.0\&.0/16 10\&.2\&.1\&.100 2001:0db8:1234::/48
.RE
.PP
hosts deny = \fIIP host address/IP netmask bits [ \&.\&.\&. ]\fR \fB(V)\fR
.RS 4
Listed hosts and nets are rejected, all others are allowed\&.
.sp
Example: hosts deny = 192\&.168\&.100/24 10\&.1\&.1\&.1 2001:db8::1428:57ab
.RE
.PP
cnid scheme = \fIbackend\fR \fB(V)\fR
.RS 4
set the CNID backend to be used for the volume, default is [@DEFAULT_CNID_SCHEME@] available schemes: [@compiled_backends@]
.RE
.PP
ea = \fInone|auto|sys|ad|samba\fR \fB(V)\fR
.RS 4
Specify how Extended Attributes.\" Extended Attributes
are stored\&.
\fBauto\fR
is the default\&.
.PP
auto
.RS 4
Try
\fBsys\fR
(by setting an EA on the shared directory itself), fallback to
\fBad\fR\&. Requires writable volume for performing test\&. "\fBread only = yes\fR" overwrites
\fBauto\fR
with
\fBnone\fR\&. Use explicit "\fBea = sys|ad\fR" for read\-only volumes where appropriate\&.
.RE
.PP
sys
.RS 4
Use filesystem Extended Attributes\&.
.RE
.PP
samba
.RS 4
Use filesystem Extended Attributes, but append a 0 byte to each xattr in order to be compatible with Samba\*(Aqs vfs_streams_xattr\&.
.RE
.PP
ad
.RS 4
Use files in
\fI\&.AppleDouble\fR
directories\&.
.RE
.PP
none
.RS 4
No Extended Attributes support\&.
.RE
.RE
.PP
mac charset = \fICHARSET\fR \fB(V)\fR
.RS 4
specifies the Mac client charset for this Volume, e\&.g\&.
\fIMAC_ROMAN\fR,
\fIMAC_CYRILLIC\fR\&. If not specified the global setting is applied\&. This setting is only required if you need volumes, where the Mac charset differs from the one globally set in the [Global] section\&.
.RE
.PP
casefold = \fBoption\fR \fB(V)\fR
.RS 4
The casefold option handles, if the case of filenames should be changed\&. The available options are:
.sp
\fBtolower\fR
\- Lowercases names in both directions\&.
.sp
\fBtoupper\fR
\- Uppercases names in both directions\&.
.sp
\fBxlatelower\fR
\- Client sees lowercase, server sees uppercase\&.
.sp
\fBxlateupper\fR
\- Client sees uppercase, server sees lowercase\&.
.RE
.PP
password = \fIpassword\fR \fB(V)\fR
.RS 4
This option allows you to set a volume password, which can be a maximum of 8 characters long (using ASCII strongly recommended at the time of this writing)\&.
.RE
.PP
file perm = \fImode\fR \fB(V)\fR, directory perm = \fImode\fR \fB(V)\fR
.RS 4
Add(or) with the client requested permissions:
\fBfile perm\fR
is for files only,
\fBdirectory perm\fR
is for directories only\&. Don\*(Aqt use with "\fBunix priv = no\fR"\&.
.PP
\fBExample.\ \&Volume for a collaborative workgroup\fR
.sp
.if n \{\
.RS 4
.\}
.nf
file perm = 0660 directory perm =
              0770
.fi
.if n \{\
.RE
.\}

.RE
.PP
umask = \fImode\fR \fB(V)\fR
.RS 4
set perm mask\&. Don\*(Aqt use with "\fBunix priv = no\fR"\&.
.RE
.PP
preexec = \fIcommand\fR \fB(V)\fR
.RS 4
command to be run when the volume is mounted
.RE
.PP
postexec = \fIcommand\fR \fB(V)\fR
.RS 4
command to be run when the volume is closed
.RE
.PP
root preexec = \fIcommand\fR \fB(V)\fR
.RS 4
command to be run as root when the volume is mounted
.RE
.PP
root postexec = \fIcommand\fR \fB(V)\fR
.RS 4
command to be run as root when the volume is closed
.RE
.PP
rolist = \fBusers/groups\fR \fB(V)\fR
.RS 4
Allows certain users and groups to have read\-only access to a share\&. This follows the allow option format\&.
.RE
.PP
rwlist = \fIusers/groups\fR \fB(V)\fR
.RS 4
Allows certain users and groups to have read/write access to a share\&. This follows the allow option format\&.
.RE
.PP
veto files = \fIvetoed names\fR \fB(V)\fR
.RS 4
hide files and directories,where the path matches one of the \*(Aq/\*(Aq delimited vetoed names\&. The veto string must always be terminated with a \*(Aq/\*(Aq, e\.&g\&. "veto files = veto1/", "veto files = veto1/veto2/"\&.
.RE
.SS "Volume options"
.PP
Boolean volume options\&.
.PP
acls = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(V)\fR
.RS 4
Whether to flag volumes as supporting ACLs\&. If ACL support is compiled in, this is yes by default\&.
.RE
.PP
case sensitive = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(V)\fR
.RS 4
Whether to flag volumes as supporting case\-sensitive filenames\&. If the filesystem is case\-insensitive, set to no\&. However, it is not fully verified\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
In spite of being case sensitive as a matter of fact, netatalk 3\&.1\&.3 and earlier did not notify kCaseSensitive flag to the client\&. Starting with 3\&.1\&.4, it is notified correctly by default\&.
.sp .5v
.RE
.RE
.PP
cnid dev = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(V)\fR
.RS 4
Whether to use the device number in the CNID backends\&. Helps when the device number is not constant across a reboot, e\&.g\&. cluster, \&.\&.\&.
.RE
.PP
convert appledouble = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(V)\fR
.RS 4
Whether automatic conversion from
\fBappledouble = v2\fR
to
\fBappledouble = ea\fR
is performed when accessing filesystems from clients\&. This is generally useful, but costs some performance\&. It\*(Aqs recommendable to run
\fBdbd\fR
on volumes and do the conversion with that\&. Then this option can be set to no\&.
.RE
.PP
delete veto files = \fIBOOLEAN\fR (default: \fIno\fR) \fB(V)\fR
.RS 4
This option is used when Netatalk is attempting to delete a directory that contains one or more vetoed files or directories (see the veto files option)\&. If this option is set to no (the default) then if a directory contains any non\-vetoed files or directories then the directory delete will fail\&. This is usually what you want\&.
.sp
If this option is set to yes, then Netatalk will attempt to recursively delete any files and directories within the vetoed directory\&.
.RE
.PP
follow symlinks = \fIBOOLEAN\fR (default: \fIno\fR) \fB(V)\fR
.RS 4
The default setting is false thus symlinks are not followed on the server\&. This is the same behaviour as OS X\*(Aqs AFP server\&. Setting the option to true causes afpd to follow symlinks on the server\&. symlinks may point outside of the AFP volume, currently afpd doesn\*(Aqt do any checks for "wide symlinks"\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
This option will subtly break when the symlinks point across filesystem boundaries\&.
.sp .5v
.RE
.RE
.PP
invisible dots = \fIBOOLEAN\fR (default: \fIno\fR) \fB(V)\fR
.RS 4
make dot files invisible\&. WARNING: enabling this option will lead to unwanted sideeffects were OS X applications when saving files to a temporary file starting with a dot first, then renaming the temp file to its final name, result in the saved file being invisible\&. The only thing this option is useful for is making files that start with a dot invisible on Mac OS 9\&. It\*(Aqs completely useless on Mac OS X, as both in Finder and in Terminal files starting with a dot are hidden anyway\&.
.RE
.PP
network ids = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(V)\fR
.RS 4
Whether the server support network ids\&. Setting this to
\fIno\fR
will result in the client not using ACL AFP functions\&.
.RE
.PP
preexec close = \fIBOOLEAN\fR (default: \fIno\fR) \fB(V)\fR
.RS 4
A non\-zero return code from preexec close the volume being immediately, preventing clients to mount/see the volume in question\&.
.RE
.PP
read only = \fIBOOLEAN\fR (default: \fIno\fR) \fB(V)\fR
.RS 4
Specifies the share as being read only for all users\&. Overwrites
\fBea = auto\fR
with
\fBea = none\fR
.RE
.PP
root preexec close= \fIBOOLEAN\fR (default: \fIno\fR) \fB(V)\fR
.RS 4
A non\-zero return code from root_preexec closes the volume immediately, preventing clients to mount/see the volume in question\&.
.RE
.PP
search db = \fIBOOLEAN\fR (default: \fIno\fR) \fB(V)\fR
.RS 4
Use fast CNID database namesearch instead of slow recursive filesystem search\&. Relies on a consistent CNID database, i\&.e\&. Samba or local filesystem access lead to inaccurate or wrong results\&. Works only for "dbd" CNID db volumes\&.
.RE
.PP
stat vol = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(V)\fR
.RS 4
Whether to stat volume path when enumerating volumes list, useful for automounting or volumes created by a preexec script\&.
.RE
.PP
time machine = \fIBOOLEAN\fR (default: \fIno\fR) \fB(V)\fR
.RS 4
Whether to enable Time Machine support for this volume\&.
.RE
.PP
unix priv = \fIBOOLEAN\fR (default: \fIyes\fR) \fB(V)\fR
.RS 4
Whether to use AFP3 UNIX privileges\&. This should be set for OS X clients\&. See also:
\fBfile perm\fR,
\fBdirectory perm\fR
and
\fBumask\fR\&.
.RE
.SH "CNID BACKENDS"
.PP
The AFP protocol mostly refers to files and directories by ID and not by name\&. Netatalk needs a way to store these ID\*(Aqs in a persistent way, to achieve this several different CNID backends are available\&. The CNID Databases are by default located in the
@localstatedir@/netatalk/CNID/(volumename)/\&.AppleDB/
directory\&.
.PP
cdb
.RS 4
"Concurrent database", backend is based on Oracle Berkley DB\&. With this backend several
\fBafpd\fR
daemons access the CNID database directly\&. Berkeley DB locking is used to synchronize access, if more than one
\fBafpd\fR
process is active for a volume\&. The drawback is, that the crash of a single
\fBafpd\fR
process might corrupt the database\&.
.RE
.PP
dbd
.RS 4
Access to the CNID database is restricted to the
\fBcnid_metad\fR
daemon process\&.
\fBafpd\fR
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
\fBcdb\fR
.RE
.PP
last
.RS 4
This backend is an exception, in terms of ID persistency\&. ID\*(Aqs are only valid for the current session\&. This is basically what
\fBafpd\fR
did in the 1\&.5 (and 1\&.6) versions\&. This backend is still available, as it is useful for e\&.g\&. sharing cdroms\&. Starting with Netatalk 3\&.0, it becomes the
\fIread only mode\fR
automatically\&.
.sp
\fBWarning\fR: It is
\fINOT\fR
recommended to use this backend for volumes anymore, as
\fBafpd\fR
now relies heavily on a persistent ID database\&. Aliases will likely not work and filename mangling is not supported\&.
.RE
.PP
Even though
\fB\&./configure \-\-help\fR
might show that there are other CNID backends available, be warned those are likely broken or mainly used for testing\&. Don\*(Aqt use them unless you know what you\*(Aqre doing, they may be removed without further notice from future versions\&.
.SH "CHARSET OPTIONS"
.PP
With OS X Apple introduced the AFP3 protocol\&. One of the most important changes was that AFP3 uses unicode names encoded as UTF\-8 decomposed\&. Previous AFP/OS versions used codepages, like MacRoman, MacCentralEurope, etc\&.
.PP
\fBafpd\fR
needs a way to preserve extended Macintosh characters, or characters illegal in unix filenames, when saving files on a unix filesystem\&. This version now uses UTF\-8 as the default encoding for names\&. \*(Aq/\*(Aq will be converted to \*(Aq:\*(Aq\&.
.PP
Earlier versions used the the so called CAP encoding\&. An extended character (>0x7F) would be converted to a :xx sequence, e\&.g\&. the Apple Logo (MacRoman: 0xF0) was saved as
:f0\&. Some special characters would be converted as to :xx notation as well\&. \*(Aq/\*(Aq would be encoded to
:2f, a leading dot \*(Aq\&.\*(Aq might be encoded as
:2e\&.
.PP
The
\fBvol charset\fR
option will allow you to select another volume encoding\&.
\fBafpd\fR
will accept any
\fBiconv\fR(1)
provided charset\&. It is highly recommended to stick to the default UTF\-8\&.
.SH "SEE ALSO"
.PP
\fBafpd\fR(8),
\fBafppasswd\fR(5),
\fBafp_signature.conf\fR(5),
\fBextmap.conf\fR(5),
\fBcnid_metad\fR(8)