1<?xml version="1.0" encoding="UTF-8"?> 2<chapter id="configuration"> 3 <title>Setting up Netatalk</title> 4 5 <sect1> 6 <title>File Services<indexterm> 7 <primary>File Services</primary> 8 9 <secondary>Netatalk's File Services</secondary> 10 </indexterm></title> 11 12 <para>Netatalk supplies AFP<indexterm> 13 <primary>AFP</primary> 14 15 <secondary>Apple Filing Protocol</secondary> 16 </indexterm> services.</para> 17 18 <sect2> 19 <title>Setting up the AFP file server</title> 20 21 <para>AFP (the Apple Filing Protocol) is the protocol Apple Macintoshes 22 use for file services. The protocol has evolved over the years. The 23 latest changes to the protocol, called "AFP 3.3", were added with the 24 release of Snow Leopard<indexterm> 25 <primary>Snow Leopard</primary> 26 27 <secondary>Mac OS X 10.6</secondary> 28 </indexterm> (Mac OS X 10.6).</para> 29 30 <para>The afpd daemon offers the fileservices to Apple clients. The only 31 configuration file is <filename>afp.conf</filename>. It uses a ini style 32 configuration syntax.</para> 33 34 <para>Mac OS X 10.5 (Leopard) added support for Time Machine backups 35 over AFP. Two new functions ensure that backups are written to spinning 36 disk, not just in the server's cache. Different host operating systems 37 honour this cache flushing differently. To make a volume a Time Machine 38 target use the volume option "<option>time machine = 39 yes</option>".</para> 40 41 <para>Starting with Netatalk 2.1 UNIX symlinks<indexterm> 42 <primary>symlink</primary> 43 44 <secondary>UNIX symlink</secondary> 45 </indexterm> can be used on the server. Semantics are the same as for 46 eg NFS, ie they are not resolved on the server side but instead it's 47 completely up to the client to resolve them, resulting in links that 48 point somewhere inside the clients filesystem view.</para> 49 50 <sect3> 51 <title>afp.conf</title> 52 53 <para><filename>afp.conf</filename> is the configuration file used by 54 afpd to determine the behaviour and configuration of the AFP file 55 serverand the AFP volume that it provides.</para> 56 57 <para>The <filename>afp.conf</filename> is divided into several 58 sections:<variablelist> 59 <varlistentry> 60 <term>[Global]</term> 61 62 <listitem> 63 <para>The global section defines general server options</para> 64 </listitem> 65 </varlistentry> 66 67 <varlistentry> 68 <term>[Homes]</term> 69 70 <listitem> 71 <para>The homes section defines user home volumes</para> 72 </listitem> 73 </varlistentry> 74 </variablelist>Any section not called <option>Global</option> or 75 <option>Homes</option> is interpreted as an AFP volume.</para> 76 77 <para>For sharing user homes by defining a <option>Homes</option> 78 section you must specify the option <option>basedir regex</option> 79 which can be a simple string with the path to the parent directory of 80 all user homes or a regular expression.</para> 81 82 <para>Example:</para> 83 84 <para><programlisting>[Homes] 85basedir regex = /home 86</programlisting></para> 87 88 <para>Now any user logging into the AFP server will have a user volume 89 available whos path is <filename>/home/NAME</filename>.</para> 90 91 <para>A more complex setup would be a server with a large amount of 92 user homes which are split across eg two different 93 filesystems:<itemizedlist> 94 <listitem> 95 <para>/RAID1/homes</para> 96 </listitem> 97 98 <listitem> 99 <para>/RAID2/morehomes</para> 100 </listitem> 101 </itemizedlist>The following configuration is 102 required:<programlisting>[Homes] 103basedir regex = /RAID./.*homes 104</programlisting></para> 105 106 <para>If <option>basedir regex</option> contains symlink, set the 107 canonicalized absolute path. When <filename>/home</filename> links to 108 <filename>/usr/home</filename>: <programlisting>[Homes] 109basedir regex = /usr/home</programlisting></para> 110 111 <para>For a more detailed explanation of the available options, please 112 refer to the <citerefentry> 113 <refentrytitle>afp.conf</refentrytitle> 114 115 <manvolnum>5</manvolnum> 116 </citerefentry> man page.</para> 117 </sect3> 118 </sect2> 119 120 <sect2 id="CNID-backends"> 121 <title>CNID<indexterm> 122 <primary>CNID</primary> 123 124 <secondary>Catalog Node ID</secondary> 125 </indexterm> backends<indexterm> 126 <primary>Backend</primary> 127 128 <secondary>CNID backend</secondary> 129 </indexterm></title> 130 131 <para>Unlike other protocols like SMB or NFS, the AFP protocol mostly 132 refers to files and directories by ID and not by a path (the IDs are 133 also called CNID, that means Catalog Node ID). A typical AFP request 134 uses a directory ID<indexterm> 135 <primary>DID</primary> 136 137 <secondary>Directory ID</secondary> 138 </indexterm> and a filename, something like <phrase>"server, please 139 open the file named 'Test' in the directory with id 167"</phrase>. For 140 example "Aliases" on the Mac basically work by ID (with a fallback to 141 the absolute path in more recent AFP clients. But this applies only to 142 Finder, not to applications).</para> 143 144 <para>Every file in an AFP volume has to have a unique file ID<indexterm> 145 <primary>FID</primary> 146 147 <secondary>File ID</secondary> 148 </indexterm>, IDs must, according to the specs, never be reused, and 149 IDs are 32 bit numbers (Directory IDs use the same ID pool). So, after 150 ~4 billion files/folders have been written to an AFP volume, the ID pool 151 is depleted and no new file can be written to the volume. No whining 152 please :-)</para> 153 154 <para>Netatalk needs to map IDs to files and folders in the host 155 filesystem. To achieve this, several different CNID backends<indexterm> 156 <primary>CNID backend</primary> 157 </indexterm> are available and can be choosed by the <option>cnid 158 scheme</option><indexterm> 159 <primary>cnidscheme</primary> 160 161 <secondary>specifying a CNID backend</secondary> 162 </indexterm> option in the <citerefentry> 163 <refentrytitle>afp.conf</refentrytitle> 164 165 <manvolnum>5</manvolnum> 166 </citerefentry> configuration file. A CNID backend is basically a 167 database storing ID <-> name mappings.</para> 168 169 <para>The CNID Databases are by default located in 170 <filename>/var/netatalk/CNID</filename>.</para> 171 172 <para>There is a command line utility called <command>dbd</command> 173 available which can be used to verify, repair and rebuild the CNID 174 database.</para> 175 176 <note> 177 <para>There are some CNID related things you should keep in mind when 178 working with netatalk:</para> 179 180 <itemizedlist> 181 <listitem> 182 <para>Don't nest volumes<indexterm> 183 <primary>Nested volumes</primary> 184 </indexterm>.</para> 185 </listitem> 186 187 <listitem> 188 <para>CNID backends are databases, so they turn afpd into a file 189 server/database mix.</para> 190 </listitem> 191 192 <listitem> 193 <para>If there's no more space on the filesystem left, the 194 database will get corrupted. You can work around this by either 195 using the <option>vol dbpath</option> option and put the database 196 files into another location or, if you use quotas, make sure the 197 CNID database folder is owned by a user/group without a 198 quota<indexterm> 199 <primary>Quotas</primary> 200 201 <secondary>Disk usage quotas</secondary> 202 </indexterm>.</para> 203 </listitem> 204 205 <listitem> 206 <para>Be careful with CNID databases for volumes that are mounted 207 via NFS. That is a pretty audacious decision to make anyway, but 208 putting a database there as well is really asking for trouble, 209 i.e. database corruption. Use the <option>vol dbpath</option> 210 directive to put the databases onto a local disk if you must use 211 NFS<indexterm> 212 <primary>NFS</primary> 213 214 <secondary>Network File System</secondary> 215 </indexterm> mounted volumes.</para> 216 </listitem> 217 </itemizedlist> 218 </note> 219 220 <sect3> 221 <title>cdb<indexterm> 222 <primary>CDB</primary> 223 224 <secondary>"cdb" CNID backend</secondary> 225 </indexterm></title> 226 227 <para>The "concurrent database" backend is based on Berkeley DB. With 228 this backend, several afpd daemons access the CNID database directly. 229 Berkeley DB locking is used to synchronize access, if more than one 230 afpd process is active for a volume. The drawback is, that the crash 231 of a single afpd process might corrupt the database. cdb should only 232 be used when sharing home directories for a larger number of users 233 <emphasis>and</emphasis> it has been determined that a large number of 234 <command>cnid_dbd</command> processes is problematic.</para> 235 </sect3> 236 237 <sect3> 238 <title>dbd<indexterm> 239 <primary>DBD</primary> 240 241 <secondary>"dbd" CNID backend</secondary> 242 </indexterm></title> 243 244 <para>Access to the CNID database is restricted to the cnid_dbd daemon 245 process. afpd processes communicate with the daemon for database reads 246 and updates. The probability for database corruption is practically 247 zero.</para> 248 249 <para>This is the default backend since Netatalk 2.1.</para> 250 </sect3> 251 252 <sect3> 253 <title>tdb<indexterm> 254 <primary>tdb</primary> 255 256 <secondary>"tdb" CNID backend</secondary> 257 </indexterm></title> 258 259 <para><abbrev>tdb</abbrev> is another persistent CNID database, it's 260 Samba's <emphasis>Trivial Database</emphasis>. It could be used 261 instead of <abbrev>cdb</abbrev> for user volumes.<important> 262 <para>Only ever use it for volumes that are 263 <emphasis>not</emphasis> shared and accessed by multiple clients 264 at once !</para> 265 </important>This backend is also used internally (as in-memory CNID 266 database) as a fallback in case opening the primary database can't be 267 opened, because <abbrev>tdb</abbrev> can work as in-memory database. 268 This of course means upon restart the CNIDs are gone.</para> 269 </sect3> 270 271 <sect3> 272 <title>last<indexterm> 273 <primary>Last</primary> 274 275 <secondary>"last" CNID backend</secondary> 276 </indexterm></title> 277 278 <para>The last backend is a in-memory tdb database. It is not 279 persistent. Starting with netatalk 3.0, it becomes the <emphasis> read 280 only mode</emphasis> automatically. This is useful e.g. for 281 CD-ROMs.</para> 282 </sect3> 283 </sect2> 284 285 <sect2 id="charsets"> 286 <title>Charsets<indexterm> 287 <primary>Charset</primary> 288 289 <secondary>character set</secondary> 290 </indexterm>/Unicode<indexterm> 291 <primary>Unicode</primary> 292 </indexterm></title> 293 294 <para></para> 295 296 <sect3> 297 <title>Why Unicode?</title> 298 299 <para>Internally, computers don't know anything about characters and 300 texts, they only know numbers. Therefore, each letter is assigned a 301 number. A character set, often referred to as 302 <emphasis>charset</emphasis> or 303 <emphasis>codepage</emphasis><indexterm> 304 <primary>Codepage</primary> 305 </indexterm>, defines the mappings between numbers and 306 letters.</para> 307 308 <para>If two or more computer systems need to communicate with each 309 other, the have to use the same character set. In the 1960s the 310 ASCII<indexterm> 311 <primary>ASCII</primary> 312 313 <secondary>American Standard Code for Information 314 Interchange</secondary> 315 </indexterm> (American Standard Code for Information Interchange) 316 character set was defined by the American Standards Association. The 317 original form of ASCII represented 128 characters, more than enough to 318 cover the English alphabet and numerals. Up to date, ASCII has been 319 the normative character scheme used by computers.</para> 320 321 <para>Later versions defined 256 characters to produce a more 322 international fluency and to include some slightly esoteric graphical 323 characters. Using this mode of encoding each character takes exactly 324 one byte. Obviously, 256 characters still wasn't enough to map all the 325 characters used in the various languages into one character 326 set.</para> 327 328 <para>As a result localized character sets were defined later, e.g the 329 ISO-8859 character sets. Most operating system vendors introduced 330 their own characters sets to satisfy their needs, e.g. IBM defined the 331 <emphasis>codepage 437 (DOSLatinUS)</emphasis>, Apple introduced the 332 <emphasis>MacRoman</emphasis><indexterm> 333 <primary>MacRoman</primary> 334 335 <secondary>MacRoman charset</secondary> 336 </indexterm> codepage and so on. The characters that were assigned 337 number larger than 127 were referred to as 338 <emphasis>extended</emphasis> characters. These character sets 339 conflict with another, as they use the same number for different 340 characters, or vice versa.</para> 341 342 <para>Almost all of those characters sets defined 256 characters, 343 where the first 128 (0-127) character mappings are identical to ASCII. 344 As a result, communication between systems using different codepages 345 was effectively limited to the ASCII charset.</para> 346 347 <para>To solve this problem new, larger character sets were defined. 348 To make room for more character mappings, these character sets use at 349 least 2 bytes to store a character. They are therefore referred to as 350 <emphasis>multibyte</emphasis> character sets.</para> 351 352 <para>One standardized multibyte charset encoding scheme is known as 353 <ulink url="http://www.unicode.org/">unicode</ulink>. A big advantage 354 of using a multibyte charset is that you only need one. There is no 355 need to make sure two computers use the same charset when they are 356 communicating.</para> 357 </sect3> 358 359 <sect3> 360 <title>character sets used by Apple</title> 361 362 <para>In the past, Apple clients used single-byte charsets to 363 communicate over the network. Over the years Apple defined a number of 364 codepages, western users will most likely be using the 365 <emphasis>MacRoman</emphasis> codepage.</para> 366 367 <para>Codepages defined by Apple include:</para> 368 369 <itemizedlist> 370 <listitem> 371 <para>MacArabic, MacFarsi</para> 372 </listitem> 373 374 <listitem> 375 <para>MacCentralEurope</para> 376 </listitem> 377 378 <listitem> 379 <para>MacChineseSimple</para> 380 </listitem> 381 382 <listitem> 383 <para>MacChineseTraditional</para> 384 </listitem> 385 386 <listitem> 387 <para>MacCroation</para> 388 </listitem> 389 390 <listitem> 391 <para>MacCyrillic</para> 392 </listitem> 393 394 <listitem> 395 <para>MacDevanagari</para> 396 </listitem> 397 398 <listitem> 399 <para>MacGreek</para> 400 </listitem> 401 402 <listitem> 403 <para>MacHebrew</para> 404 </listitem> 405 406 <listitem> 407 <para>MacIcelandic</para> 408 </listitem> 409 410 <listitem> 411 <para>MacJapanese</para> 412 </listitem> 413 414 <listitem> 415 <para>MacKorean</para> 416 </listitem> 417 418 <listitem> 419 <para>MacRoman</para> 420 </listitem> 421 422 <listitem> 423 <para>MacRomanian</para> 424 </listitem> 425 426 <listitem> 427 <para>MacThai</para> 428 </listitem> 429 430 <listitem> 431 <para>MacTurkish</para> 432 </listitem> 433 </itemizedlist> 434 435 <para>Starting with Mac OS X and AFP3, <ulink 436 url="http://www.utf-8.com/">UTF-8</ulink> is used. UTF-8 encodes 437 Unicode characters in an ASCII compatible way, each Unicode character 438 is encoded into 1-6 ASCII characters. UTF-8 is therefore not really a 439 charset itself, it's an encoding of the Unicode charset.</para> 440 441 <para>To complicate things, Unicode defines several <emphasis> <ulink 442 url="http://www.unicode.org/reports/tr15/index.html">normalization</ulink> 443 </emphasis> forms. While <ulink 444 url="http://www.samba.org">samba</ulink><indexterm> 445 <primary>Samba</primary> 446 </indexterm> uses <emphasis>precomposed</emphasis><indexterm> 447 <primary>Precomposed</primary> 448 449 <secondary>Precomposed Unicode normalization</secondary> 450 </indexterm> Unicode, which most Unix tools prefer as well, Apple 451 decided to use the <emphasis>decomposed</emphasis><indexterm> 452 <primary>Decomposed</primary> 453 454 <secondary>Decomposed Unicode normalization</secondary> 455 </indexterm> normalization.</para> 456 457 <para>For example lets take the German character 458 '<keycode>��</keycode>'. Using the precomposed normalization, Unicode 459 maps this character to 0xE4. In decomposed normalization, '��' is 460 actually mapped to two characters, 0x61 and 0x308. 0x61 is the mapping 461 for an 'a', 0x308 is the mapping for a <emphasis>COMBINING 462 DIAERESIS</emphasis>.</para> 463 464 <para>Netatalk refers to precomposed UTF-8 as 465 <emphasis>UTF8</emphasis><indexterm> 466 <primary>UTF8</primary> 467 468 <secondary>Netatalk's precomposed UTF-8 encoding</secondary> 469 </indexterm> and to decomposed UTF-8 as 470 <emphasis>UTF8-MAC</emphasis><indexterm> 471 <primary>UTF8-MAC</primary> 472 473 <secondary>Netatalk's decomposed UTF-8 encoding</secondary> 474 </indexterm>.</para> 475 </sect3> 476 477 <sect3> 478 <title>afpd and character sets</title> 479 480 <para>To support new AFP 3.x and older AFP 2.x clients at the same 481 time, afpd needs to be able to convert between the various charsets 482 used. AFP 3.x clients always use UTF8-MAC, AFP 2.x clients use one of 483 the Apple codepages.</para> 484 485 <para>At the time of this writing, netatalk supports the following 486 Apple codepages:</para> 487 488 <itemizedlist> 489 <listitem> 490 <para>MAC_CENTRALEUROPE</para> 491 </listitem> 492 493 <listitem> 494 <para>MAC_CHINESE_SIMP</para> 495 </listitem> 496 497 <listitem> 498 <para>MAC_CHINESE_TRAD</para> 499 </listitem> 500 501 <listitem> 502 <para>MAC_CYRILLIC</para> 503 </listitem> 504 505 <listitem> 506 <para>MAC_GREEK</para> 507 </listitem> 508 509 <listitem> 510 <para>MAC_HEBREW</para> 511 </listitem> 512 513 <listitem> 514 <para>MAC_JAPANESE</para> 515 </listitem> 516 517 <listitem> 518 <para>MAC_KOREAN</para> 519 </listitem> 520 521 <listitem> 522 <para>MAC_ROMAN</para> 523 </listitem> 524 525 <listitem> 526 <para>MAC_TURKISH</para> 527 </listitem> 528 </itemizedlist> 529 530 <para>afpd handles three different character set options:</para> 531 532 <variablelist> 533 <varlistentry> 534 <term>unix charset<indexterm> 535 <primary>unix charset</primary> 536 537 <secondary>afpd's unix charset setting</secondary> 538 </indexterm></term> 539 540 <listitem> 541 <para>This is the codepage used internally by your operating 542 system. If not specified, it defaults to <option>UTF8</option>. 543 If <option>LOCALE</option> is specified and your system support 544 Unix locales, afpd tries to detect the codepage. afpd uses this 545 codepage to read its configuration files, so you can use 546 extended characters for volume names, login messages, etc. see 547 <citerefentry> 548 <refentrytitle>afp.conf</refentrytitle> 549 550 <manvolnum>5</manvolnum> 551 </citerefentry>.</para> 552 </listitem> 553 </varlistentry> 554 555 <varlistentry> 556 <term>mac charset<indexterm> 557 <primary>mac charset</primary> 558 559 <secondary>afpd's mac charset setting</secondary> 560 </indexterm></term> 561 562 <listitem> 563 <para>As already mentioned, older Mac OS clients (up to AFP 2.2) 564 use codepages to communicate with afpd. However, there is no 565 support for negotiating the codepage used by the client in the 566 AFP protocol. If not specified otherwise, afpd assumes the 567 <emphasis>MacRoman</emphasis> codepage is used. In case you're 568 clients use another codepage, e.g. 569 <emphasis>MacCyrillic</emphasis>, you'll <emphasis 570 role="bold">have</emphasis> to explicitly configure this. see 571 <citerefentry> 572 <refentrytitle>afp.conf</refentrytitle> 573 574 <manvolnum>5</manvolnum> 575 </citerefentry>.</para> 576 </listitem> 577 </varlistentry> 578 579 <varlistentry> 580 <term>vol charset<indexterm> 581 <primary>vol charset</primary> 582 583 <secondary>afpd's vol charset setting</secondary> 584 </indexterm></term> 585 586 <listitem> 587 <para>This defines the charset afpd should use for filenames on 588 disk. By default, it is the same as <option>unix 589 charset</option>. If you have <ulink 590 url="http://www.gnu.org/software/libiconv/">iconv</ulink><indexterm> 591 <primary>Iconv</primary> 592 593 <secondary>iconv encoding conversion engine</secondary> 594 </indexterm> installed, you can use any iconv provided charset 595 as well.</para> 596 597 <para>afpd needs a way to preserve extended macintosh 598 characters, or characters illegal in unix filenames, when saving 599 files on a unix filesystem. Earlier versions used the the so 600 called CAP encoding<indexterm> 601 <primary>CAP encoding</primary> 602 603 <secondary>CAP style character encoding</secondary> 604 </indexterm>. An extended character (>0x7F) would be 605 converted to a :xx hex sequence, e.g. the Apple Logo (MacRoman: 606 0xF0) was saved as :f0. Some special characters will be 607 converted as to :xx notation as well. '/' will be encoded to 608 :2f, if <option>usedots</option> was not specified, a leading 609 dot '.' will be encoded as :2e.</para> 610 611 <para>Even though this version now uses <option>UTF8</option> as 612 the default encoding for filenames, '/' will be converted to 613 ':'. For western users another useful setting could be 614 <option>vol charset = ISO-8859-15</option>.</para> 615 616 <para>If a character cannot be converted from the <option>mac 617 charset</option> to the selected <option>vol charset</option>, 618 afpd will save it as a CAP encoded character. For AFP3 clients, 619 afpd will convert the UTF8 character to <option>mac 620 charset</option> first. If this conversion fails, you'll receive 621 a -50 error on the mac. <emphasis>Note</emphasis>: Whenever you 622 can, please stick with the default UTF8 volume format. see 623 <citerefentry> 624 <refentrytitle>afp.conf</refentrytitle> 625 626 <manvolnum>5</manvolnum> 627 </citerefentry>.</para> 628 </listitem> 629 </varlistentry> 630 </variablelist> 631 </sect3> 632 </sect2> 633 634 <sect2 id="authentication"> 635 <title>Authentication<indexterm> 636 <primary>Authentication</primary> 637 638 <secondary>between AFP client and server</secondary> 639 </indexterm></title> 640 641 <sect3> 642 <title>AFP authentication basics</title> 643 644 <para>Apple chose a flexible model called "User Authentication 645 Modules"<indexterm> 646 <primary>UAM</primary> 647 648 <secondary>User Authentication Module</secondary> 649 </indexterm> (UAMs) for authentication purposes between AFP client 650 and server. An AFP client initially connecting to an AFP server will 651 ask for the list of UAMs which the server provides, and will choose 652 the one with strongest encryption that the client supports.</para> 653 654 <para>Several UAMs have been developed by Apple over the time, some by 655 3rd-party developers.</para> 656 </sect3> 657 658 <sect3> 659 <title>UAMs supported by Netatalk</title> 660 661 <para>Netatalk supports the following ones by default:</para> 662 663 <itemizedlist> 664 <listitem> 665 <para>"No User Authent"<indexterm> 666 <primary>No User Authent</primary> 667 668 <secondary>"No User Authent" UAM (guest access)</secondary> 669 </indexterm> UAM (guest access without authentication)</para> 670 </listitem> 671 672 <listitem> 673 <para>"Cleartxt Passwrd"<indexterm> 674 <primary>Cleartxt Passwrd</primary> 675 676 <secondary>"Cleartxt Passwrd" UAM</secondary> 677 </indexterm> UAM (no password encryption)</para> 678 </listitem> 679 680 <listitem> 681 <para>"Randnum exchange"<indexterm> 682 <primary>Randnum exchange</primary> 683 684 <secondary>"Randnum exchange" UAM</secondary> 685 </indexterm>/"2-Way Randnum exchange"<indexterm> 686 <primary>2-Way Randnum exchange</primary> 687 688 <secondary>"2-Way Randnum exchange" UAM</secondary> 689 </indexterm> UAMs (weak password encryption, separate password 690 storage)</para> 691 </listitem> 692 693 <listitem> 694 <para>"DHCAST128"<indexterm> 695 <primary>DHCAST128</primary> 696 697 <secondary>"DHCAST128" UAM</secondary> 698 </indexterm> UAM (stronger password encryption)</para> 699 </listitem> 700 701 <listitem> 702 <para>"DHX2"<indexterm> 703 <primary>DHX2</primary> 704 705 <secondary>"DHX2" UAM</secondary> 706 </indexterm> UAM (successor of DHCAST128)</para> 707 </listitem> 708 </itemizedlist> 709 710 <para>There exist other optional UAMs as well:</para> 711 712 <itemizedlist> 713 <listitem> 714 <para>"PGPuam 1.0"<indexterm> 715 <primary>PGPuam 1.0</primary> 716 717 <secondary>"PGPuam 1.0" UAM</secondary> 718 </indexterm><indexterm> 719 <primary>uams_pgp.so</primary> 720 721 <secondary>"PGPuam 1.0" UAM</secondary> 722 </indexterm> UAM (PGP-based authentication for pre-Mac OS X 723 clients. You'll also need the <ulink 724 url="http://www.vmeng.com/vinnie/papers/pgpuam.html">PGPuam 725 client</ulink> to let this work)</para> 726 727 <para>You'll have to add <filename>"--enable-pgp-uam"</filename> 728 to your configure switches to have this UAM available.</para> 729 </listitem> 730 731 <listitem> 732 <para>"Kerberos IV"<indexterm> 733 <primary>Kerberos IV</primary> 734 735 <secondary>"Kerberos IV" UAM</secondary> 736 </indexterm><indexterm> 737 <primary>uams_krb4.so</primary> 738 739 <secondary>"Kerberos IV" UAM</secondary> 740 </indexterm>/"AFS Kerberos"<indexterm> 741 <primary>AFS Kerberos</primary> 742 743 <secondary>"AFS Kerberos" UAM (Kerberos IV)</secondary> 744 </indexterm> UAMs (suitable to use <ulink 745 url="http://web.mit.edu/macdev/KfM/Common/Documentation/faq.html">Kerberos 746 v4 based authentication</ulink> and AFS file servers)</para> 747 748 <para>Use <filename>"--enable-krb4-uam"</filename> at compile time 749 to activate the build of this UAM.</para> 750 </listitem> 751 752 <listitem> 753 <para>"Client Krb v2"<indexterm> 754 <primary>Client Krb v2</primary> 755 756 <secondary>"Client Krb v2" UAM (Kerberos V)</secondary> 757 </indexterm> UAM (Kerberos V, suitable for "Single Sign On" 758 Scenarios with OS X clients -- see below)</para> 759 760 <para><filename>"--enable-krbV-uam"</filename> will provide you 761 with the ability to use this UAM.</para> 762 </listitem> 763 </itemizedlist> 764 765 <para>You can configure which UAMs should be activated by defining 766 "<option>uam list</option>" in <option>Global</option> section. 767 <command>afpd</command> will log which UAMs it's using and if problems 768 occur while activating them in either 769 <filename>netatalk.log</filename> or syslog at startup time. 770 <citerefentry> 771 <refentrytitle>asip-status.pl</refentrytitle> 772 773 <manvolnum>1</manvolnum> 774 </citerefentry> can be used to query the available UAMs of AFP 775 servers as well.</para> 776 777 <para>Having a specific UAM available at the server does not 778 automatically mean that a client can use it. Client-side support is 779 also necessary. For older Macintoshes running Mac OS < X DHCAST128 780 support exists since AppleShare client 3.8.x.</para> 781 782 <para>On OS X, there exist some client-side techniques to make the 783 AFP-client more verbose, so one can have a look what's happening while 784 negotiating the UAMs to use. Compare with this <ulink 785 url="http://article.gmane.org/gmane.network.netatalk.devel/7383/">hint</ulink>.</para> 786 </sect3> 787 788 <sect3> 789 <title>Which UAMs to activate?</title> 790 791 <para>It depends primarily on your needs and on the kind of Mac OS 792 versions you have to support. Basically one should try to use 793 DHCAST128 and DHX2 where possible because of its strength of password 794 encryption.</para> 795 796 <itemizedlist> 797 <listitem> 798 <para>Unless you really have to supply guest access to your 799 server's volumes ensure that you disable "No User Authent" since 800 it might lead accidentally to unauthorized access. In case you 801 must enable guest access take care that you enforce this on a per 802 volume base using the access controls.</para> 803 </listitem> 804 805 <listitem> 806 <para>The "ClearTxt Passwrd" UAM is as bad as it sounds since 807 passwords go unencrypted over the wire. Try to avoid it at both 808 the server's side as well as on the client's. Note: If you want to 809 provide Mac OS 8/9 clients with NetBoot-services then you need 810 uams_cleartext.so since the AFP-client integrated into the Mac's 811 firmware can only deal with this basic form of 812 authentication.</para> 813 </listitem> 814 815 <listitem> 816 <para>Since "Randnum exchange"/"2-Way Randnum exchange" uses only 817 56 bit DES for encryption it should be avoided as well. Another 818 disadvantage is the fact that the passwords have to be stored in 819 cleartext on the server and that it doesn't integrate into both 820 PAM scenarios or classic /etc/shadow (you have to administrate 821 passwords separately by using the <citerefentry> 822 <refentrytitle>afppasswd</refentrytitle> 823 824 <manvolnum>1</manvolnum> 825 </citerefentry> utility, if clients should use these 826 UAMs)</para> 827 </listitem> 828 829 <listitem> 830 <para>"DHCAST128" or "DHX2" should be a good compromise for most 831 people since it combines stronger encryption with PAM 832 integration.</para> 833 </listitem> 834 835 <listitem> 836 <para>Using the Kerberos V<indexterm> 837 <primary>Kerberos V</primary> 838 839 <secondary>"Client Krb v2" UAM</secondary> 840 </indexterm> ("Client Krb v2") UAM, it's possible to implement 841 real single sign on scenarios using Kerberos tickets. The password 842 is not sent over the network. Instead, the user password is used 843 to decrypt a service ticket for the appleshare server. The service 844 ticket contains an encryption key for the client and some 845 encrypted data (which only the appleshare server can decrypt). The 846 encrypted portion of the service ticket is sent to the server and 847 used to authenticate the user. Because of the way that the afpd 848 service principal detection is implemented, this authentication 849 method is vulnerable to man-in-the-middle attacks.</para> 850 </listitem> 851 </itemizedlist> 852 853 <para>For a more detailed overview over the technical implications of 854 the different UAMs, please have a look at Apple's <ulink 855 url="http://developer.apple.com/library/mac/#documentation/Networking/Conceptual/AFP/AFPSecurity/AFPSecurity.html#//apple_ref/doc/uid/TP40000854-CH232-SW1">File 856 Server Security</ulink> pages.</para> 857 </sect3> 858 859 <sect3> 860 <title>Using different authentication sources with specific 861 UAMs</title> 862 863 <para>Some UAMs provide the ability to use different authentication 864 "backends", namely <filename>uams_cleartext.so</filename>, 865 <filename>uams_dhx.so</filename> and 866 <filename>uams_dhx2.so</filename>. They can use either classic Unix 867 passwords from <filename>/etc/passwd</filename> 868 (<filename>/etc/shadow</filename>) or PAM if the system supports that. 869 <filename>uams_cleartext.so</filename> can be symlinked to either 870 <filename>uams_passwd.so</filename> or 871 <filename>uams_pam.so</filename>, <filename>uams_dhx.so</filename> to 872 <filename>uams_dhx_passwd.so</filename> or 873 <filename>uams_dhx_pam.so</filename> and 874 <filename>uams_dhx2.so</filename> to 875 <filename>uams_dhx2_passwd.so</filename> or 876 <filename>uams_dhx2_pam.so</filename>.</para> 877 878 <para>So, if it looks like this in Netatalk's UAMs folder (per default 879 <filename>/etc/netatalk/uams/</filename>):<programlisting>uams_clrtxt.so -> uams_pam.so 880uams_dhx.so -> uams_dhx_pam.so 881uams_dhx2.so -> uams_dhx2_pam.so</programlisting> then you're using PAM, 882 otherwise classic Unix passwords. The main advantage of using PAM is 883 that one can integrate Netatalk in centralized authentication 884 scenarios, eg. via LDAP, NIS and the like. Please always keep in mind 885 that the protection of your user's login credentials in such scenarios 886 also depends on the strength of encryption that the UAM in question 887 supplies. So think about eliminating weak UAMs like "ClearTxt Passwrd" 888 and "Randnum exchange" completely from your network.</para> 889 </sect3> 890 891 <sect3> 892 <title>Netatalk UAM overview table</title> 893 894 <para>A small overview of the most common used UAMs.</para> 895 896 <table orient="land"> 897 <title>Netatalk UAM overview</title> 898 899 <tgroup align="center" cols="7"> 900 <colspec colname="col1" colnum="1" colwidth="0.5*" /> 901 902 <colspec colname="uam_guest" colnum="2" colwidth="1*" /> 903 904 <colspec colname="uam_clrtxt" colnum="3" colwidth="1*" /> 905 906 <colspec colname="uam_randnum" colnum="4" colwidth="1*" /> 907 908 <colspec colname="uam_dhx" colnum="5" colwidth="1*" /> 909 910 <colspec colname="uam_dhx2" colnum="6" colwidth="1*" /> 911 912 <colspec colname="uam_gss" colnum="7" colwidth="1*" /> 913 914 <tbody> 915 <row> 916 <entry align="center" rotate="0" valign="middle">UAM</entry> 917 918 <entry>No User Authent<indexterm> 919 <primary>uams_guest.so</primary> 920 921 <secondary>"No User Authent" UAM (guest 922 access)</secondary> 923 </indexterm></entry> 924 925 <entry>Cleartxt Passwrd<indexterm> 926 <primary>uams_cleartxt.so</primary> 927 928 <secondary>"Cleartxt Passwrd" UAM</secondary> 929 </indexterm></entry> 930 931 <entry>(2-Way) Randnum exchange<indexterm> 932 <primary>uams_randnum.so</primary> 933 934 <secondary>"(2-Way) Randnum exchange" UAM</secondary> 935 </indexterm></entry> 936 937 <entry>DHCAST128<indexterm> 938 <primary>uams_dhx.so</primary> 939 940 <secondary>"DHCAST128" UAM</secondary> 941 </indexterm></entry> 942 943 <entry>DHX2<indexterm> 944 <primary>uams_dhx2.so</primary> 945 946 <secondary>"DHX2" UAM</secondary> 947 </indexterm></entry> 948 949 <entry>Client Krb v2<indexterm> 950 <primary>uams_gss.so</primary> 951 952 <secondary>"Client Krb v2" UAM (Kerberos V)</secondary> 953 </indexterm></entry> 954 </row> 955 956 <row> 957 <entry align="center" rotate="0" valign="middle">pssword 958 length</entry> 959 960 <entry>guest access</entry> 961 962 <entry>max. 8 characters</entry> 963 964 <entry>max. 8 characters</entry> 965 966 <entry>max. 64 characters</entry> 967 968 <entry>max. 256 characters</entry> 969 970 <entry>Kerberos tickets</entry> 971 </row> 972 973 <row> 974 <entry align="center" rotate="0" valign="middle">Client 975 support</entry> 976 977 <entry>built-in into all Mac OS versions</entry> 978 979 <entry>built-in in all Mac OS versions except 10.0. Has to be 980 activated explicitly in recent Mac OS X versions</entry> 981 982 <entry>built-in into almost all Mac OS versions</entry> 983 984 <entry>built-in since AppleShare client 3.8.4, available as a 985 plug-in for 3.8.3, integrated in Mac OS X' AFP client</entry> 986 987 <entry>built-in since Mac OS X 10.2</entry> 988 989 <entry>built-in since Mac OS X 10.2</entry> 990 </row> 991 992 <row> 993 <entry align="center" rotate="0" 994 valign="middle">Encryption</entry> 995 996 <entry>Enables guest access without authentication between 997 client and server.</entry> 998 999 <entry>Password will be sent in cleartext over the wire. Just 1000 as bad as it sounds, therefore avoid at all if possible (note: 1001 providing NetBoot services requires the ClearTxt UAM)</entry> 1002 1003 <entry>8-byte random numbers are sent over the wire, 1004 comparable with DES, 56 bits. Vulnerable to offline dictionary 1005 attack. Requires passwords in clear on the server.</entry> 1006 1007 <entry>Password will be encrypted with 128 bit SSL, user will 1008 be authenticated against the server but not vice versa. 1009 Therefor weak against man-in-the-middle attacks.</entry> 1010 1011 <entry>Password will be encrypted using libgcrypt with CAST 1012 128 in CBC mode. User will be authenticated against the server 1013 but not vice versa. Therefor weak against man-in-the-middle 1014 attacks.</entry> 1015 1016 <entry>Password is not sent over the network. Due to the 1017 service principal detection method, this authentication method 1018 is vulnerable to man-in-the-middle attacks.</entry> 1019 </row> 1020 1021 <row> 1022 <entry align="center" rotate="0" valign="middle">Server 1023 support</entry> 1024 1025 <entry align="center" valign="middle">uams_guest.so</entry> 1026 1027 <entry align="center" valign="middle">uams_cleartxt.so</entry> 1028 1029 <entry align="center" valign="middle">uams_randnum.so</entry> 1030 1031 <entry align="center" valign="middle">uams_dhx.so</entry> 1032 1033 <entry align="center" valign="middle">uams_dhx2.so</entry> 1034 1035 <entry align="center" valign="middle">uams_gss.so</entry> 1036 </row> 1037 1038 <row> 1039 <entry align="center" rotate="0" valign="middle">Password 1040 storage method</entry> 1041 1042 <entry align="center" valign="middle">None</entry> 1043 1044 <entry align="center" valign="middle">Either /etc/passwd 1045 (/etc/shadow) or PAM</entry> 1046 1047 <entry align="center" valign="middle">Passwords stored in 1048 clear text in a separate text file</entry> 1049 1050 <entry align="center" valign="middle">Either /etc/passwd 1051 (/etc/shadow) or PAM</entry> 1052 1053 <entry align="center" valign="middle">Either /etc/passwd 1054 (/etc/shadow) or PAM</entry> 1055 1056 <entry align="center" valign="middle">At the Kerberos Key 1057 Distribution Center*</entry> 1058 </row> 1059 </tbody> 1060 </tgroup> 1061 </table> 1062 1063 <para>* Have a look at this <ulink 1064 url="http://cryptnet.net/fdp/admin/kerby-infra/en/kerby-infra.html">Kerberos 1065 overview</ulink></para> 1066 </sect3> 1067 1068 <sect3 id="sshtunnel"> 1069 <title>SSH tunneling</title> 1070 1071 <para>Tunneling and all sort of VPN stuff has nothing to do with AFP 1072 authentication and UAMs in general. But since Apple introduced an 1073 option called "Allow Secure Connections Using SSH" and many people 1074 tend to confuse both things, we'll speak about that here too.</para> 1075 1076 <sect4 id="manualsshtunnel"> 1077 <title>Manually tunneling an AFP session</title> 1078 1079 <para>This works since the first AFP servers that spoke "AFP over 1080 TCP" appeared in networks. One simply tunnels the remote server's 1081 AFP port to a local port different than 548 and connects locally to 1082 this port afterwards. On OS X this can be done by</para> 1083 1084 <programlisting>ssh -l $USER $SERVER -L 10548:127.0.0.1:548 sleep 3000</programlisting> 1085 1086 <para>After establishing the tunnel one will use 1087 <filename>"afp://127.0.0.1:10548"</filename> in the "Connect to 1088 server" dialog. All AFP traffic including the initial connection 1089 attempts will be sent encrypted over the wire since the local AFP 1090 client will connect to the Mac's local port 10548 which will be 1091 forwarded to the remote server's AFP port (we used the default 548) 1092 over SSH.</para> 1093 1094 <para>These sorts of tunnels are an ideal solution if you've to 1095 access an AFP server providing weak authentications mechanisms 1096 through the Internet without having the ability to use a "real" VPN. 1097 Note that you can let <command>ssh</command> compress the data by 1098 using its "-C" switch and that the tunnel endpoints can be different 1099 from both AFP client and server (compare with the SSH documentation 1100 for details).</para> 1101 </sect4> 1102 1103 <sect4 id="autosshtunnel"> 1104 <title>Automatically establishing a tunneled AFP connection</title> 1105 1106 <para>From Mac OS X 10.2 to 10.4, Apple added an "Allow Secure 1107 Connections Using SSH" checkbox to the "Connect to Server" dialog. 1108 The idea behind: When the server signals that it can be contacted by 1109 SSH then Mac OS X' AFP client tries to establish the tunnel and 1110 automagically sends all AFP traffic through it.</para> 1111 1112 <para>But it took until the release of Mac OS X 10.3 that this 1113 feature worked the first time... partly. In case, the SSH tunnel 1114 can't be established the AFP client <emphasis 1115 role="strong">silently</emphasis> fell back to an unencrypted AFP 1116 connection attempt.</para> 1117 1118 <para>Netatalk's afpd will report that it is capable of handling SSH 1119 tunneled AFP requests, when both "<option>advertise ssh</option>" 1120 and "<option>fqdn</option>" options are set in 1121 <option>Global</option> section (double check with <citerefentry> 1122 <refentrytitle>asip-status.pl</refentrytitle> 1123 1124 <manvolnum>1</manvolnum> 1125 </citerefentry> after you restarted afpd when you made changes to 1126 the settings). But there are a couple of reasons why you don't want 1127 to use this option at all:</para> 1128 1129 <itemizedlist> 1130 <listitem> 1131 <para>Tunneling TCP over TCP (as SSH does) is not the best idea. 1132 There exist better solutions like VPNs based on the IP 1133 layer.</para> 1134 </listitem> 1135 1136 <listitem> 1137 <para>Since this SSH kludge isn't a normal UAM that integrates 1138 directly into the AFP authentication mechanisms but instead uses 1139 a single flag signalling clients whether they can <emphasis 1140 role="strong">try</emphasis> to establish a tunnel or not, it 1141 makes life harder to see what's happening when things go 1142 wrong.</para> 1143 </listitem> 1144 1145 <listitem> 1146 <para>You cannot control which machines are logged on by 1147 Netatalk tools like a <command>macusers</command> since all 1148 connection attempts seem to be made from localhost.</para> 1149 </listitem> 1150 1151 <listitem> 1152 <para>On the other side you've to limit access to afpd to 1153 localhost only (TCP wrappers) when you want to ensure that all 1154 AFP sessions are SSH encrypted or...</para> 1155 </listitem> 1156 1157 <listitem> 1158 <para>...when you're using 10.2 - 10.3.3 then you get the 1159 opposite of what you'd expect: potentially unencrypted AFP 1160 communication (including logon credentials) on the network 1161 without a single notification that establishing the tunnel 1162 failed. Apple fixed that not until Mac OS X 10.3.4.</para> 1163 </listitem> 1164 1165 <listitem> 1166 <para>Encrypting all AFP sessions via SSH can lead to a 1167 significantly higher load on the Netatalk server</para> 1168 </listitem> 1169 </itemizedlist> 1170 </sect4> 1171 </sect3> 1172 </sect2> 1173 1174 <sect2 id="acls"> 1175 <title>ACL Support<indexterm> 1176 <primary>ACLs</primary> 1177 </indexterm></title> 1178 1179 <para>ACL support for AFP is implemented for ZFS ACLs on Solaris and 1180 derived platforms and for POSIX 1e ACLs on Linux.</para> 1181 1182 <sect3> 1183 <title>Configuration</title> 1184 1185 <para>For a basic mode of operation there's nothing to configure. 1186 Netatalk reads ACLs on the fly and calculates effective permissions 1187 which are then send to the AFP client via the so called 1188 UARights<indexterm> 1189 <primary>UARights</primary> 1190 </indexterm> permission bits. On a Mac, the Finder uses these bits 1191 to adjust permission in Finder windows. For example folder whos UNIX 1192 mode would only result in in read-only permissions for a user will not 1193 be displayed with a read-only icon and the user will be able to write 1194 to the folder given the folder has an ACL giving the user write 1195 access.</para> 1196 1197 <para>By default, the effective permission of the authenticated user 1198 are only mapped to the mentioned UARights<indexterm> 1199 <primary>UARights</primary> 1200 </indexterm>permission structure, not the UNIX mode. You can adjust 1201 this behaviour with the configuration option <link 1202 linkend="map_acls">map acls</link>.</para> 1203 1204 <para>However, neither in Finder "Get Info" windows nor in Terminal 1205 will you be able to see the ACLs, that's a result of how ACLs in OS X 1206 are designed. If you want to be able to display ACLs on the client, 1207 things get more involved as you must then setup both client and server 1208 to be part on a authentication domain (directory service, eg LDAP, 1209 OpenDirectory). The reason is, that in OS X ACLs are bound to UUIDs, 1210 not just uid's or gid's. Therefor afpd must be able to map every 1211 filesystem uid and gid to a UUID so that it can return the server side 1212 ACLs which are bound to UNIX uid and gid mapped to OS X UUIDs.</para> 1213 1214 <para>Netatalk can query a directory server using LDAP queries. Either 1215 the directory server already provides an UUID attribute for user and 1216 groups (Active Directory, Open Directory) or you reuse an unused 1217 attribute (or add a new one) to you directory server (eg 1218 OpenLDAP).</para> 1219 1220 <para>In detail:</para> 1221 1222 <orderedlist> 1223 <listitem> 1224 <para>For Solaris/ZFS: ZFS Volumes</para> 1225 1226 <para>You should configure a ZFS ACL know for any volume you want 1227 to use with Netatalk:</para> 1228 1229 <screen>aclinherit = passthrough 1230aclmode = passthrough</screen> 1231 1232 <para>For an explanation of what this knob does and how to apply 1233 it, check your hosts ZFS documentation (eg man zfs).</para> 1234 </listitem> 1235 1236 <listitem> 1237 <para>Authentication Domain</para> 1238 1239 <para>Your server and the clients must be part of a security 1240 association where identity data is coming from a common source. 1241 ACLs in Darwin are based on UUIDs and so is the ACL specification 1242 in AFP 3.2. Therefor your source of identity data has to provide 1243 an attribute for every user and group where a UUID is stored as a 1244 ASCII string. In other words:</para> 1245 1246 <itemizedlist> 1247 <listitem> 1248 <para>you need an Open Directory Server or an LDAP server 1249 where you store UUIDs in some attribute</para> 1250 </listitem> 1251 1252 <listitem> 1253 <para>your clients must be configured to use this 1254 server</para> 1255 </listitem> 1256 1257 <listitem> 1258 <para>your server should be configured to use this server via 1259 nsswitch and PAM</para> 1260 </listitem> 1261 1262 <listitem> 1263 <para>configure Netatalk via the special <link 1264 linkend="acl_options">LDAP options for ACLs</link> in <link 1265 linkend="afp.conf.5">afp.conf</link> so that Netatalk is able 1266 to retrieve the UUID for users and groups via LDAP search 1267 queries</para> 1268 </listitem> 1269 </itemizedlist> 1270 </listitem> 1271 </orderedlist> 1272 </sect3> 1273 1274 <sect3> 1275 <title>OS X ACLs</title> 1276 1277 <para>With Access Control Lists (ACLs) Mac OS X offers a powerful 1278 extension of the traditional UNIX permissions model. An ACL is an 1279 ordered list of Access Control Entries (ACEs) explicitly granting or 1280 denying a set of permissions to a given user or group.</para> 1281 1282 <para>Unlike UNIX permissions, which are bound to user or group IDs, 1283 ACLs are tied to UUIDs. For this reason accessing an object's ACL 1284 requires server and client to use a common directory service which 1285 translates between UUIDs and user/group IDs.</para> 1286 1287 <para>ACLs and UNIX permissions interact in a rather simple way. As 1288 ACLs are optional UNIX permissions act as a default mechanism for 1289 access control. Changing an objects's UNIX permissions will leave it's 1290 ACL intact and modifying an ACL will never change the object's UNIX 1291 permissions. While doing access checks, OS X first examines an 1292 object's ACL evaluating ACEs in order until all requested rights have 1293 been granted, a requested right has been explicitly denied by an ACE 1294 or the end of the list has been reached. In case there is no ACL or 1295 the permissions granted by the ACL are not sufficient to fulfill the 1296 request, OS X next evaluates the object's UNIX permissions. Therefore 1297 ACLs always have precedence over UNIX permissions.</para> 1298 </sect3> 1299 1300 <sect3> 1301 <title>ZFS ACLs</title> 1302 1303 <para>ZFS ACLs closely match OS X ACLs. Both offer mostly identical 1304 fine grained permissions and inheritance settings.</para> 1305 </sect3> 1306 1307 <sect3> 1308 <title>POSIX ACLs</title> 1309 1310 <sect4> 1311 <title>Overview</title> 1312 1313 <para>Compared to OS X or NFSv4 ACLs, Posix ACLs represent a 1314 different, less versatile approach to overcome the limitations of 1315 the traditional UNIX permissions. Implementations are based on the 1316 withdrawn Posix 1003.1e standard.</para> 1317 1318 <para>The standard defines two types of ACLs. Files and directories 1319 can have access ACLs which are consulted for access checks. 1320 Directories can also have default ACLs irrelevant to access checks. 1321 When a new object is created inside a directory with a default ACL, 1322 the default ACL is applied to the new object as it's access ACL. 1323 Subdirectories inherit default ACLs from their parent. There are no 1324 further mechanisms of inheritance control. </para> 1325 1326 <para>Architectural differences between Posix ACLs and OS X ACLs 1327 especially involve:</para> 1328 1329 <para><itemizedlist> 1330 <listitem> 1331 <para>No fine-granular permissions model. Like UNIX 1332 permissions Posix ACLs only differentiate between read, write 1333 and execute permissions.</para> 1334 </listitem> 1335 1336 <listitem> 1337 <para>Entries within an ACL are unordered.</para> 1338 </listitem> 1339 1340 <listitem> 1341 <para>Posix ACLs can only grant rights. There is no way to 1342 explicitly deny rights by an entry.</para> 1343 </listitem> 1344 1345 <listitem> 1346 <para>UNIX permissions are integrated into an ACL as special 1347 entries.</para> 1348 </listitem> 1349 </itemizedlist></para> 1350 1351 <para>Posix 1003.1e defines 6 different types of ACL entries. The 1352 first three types are used to integrate standard UNIX permissions. 1353 They form a minimal ACL, their presence is mandatory and only one 1354 entry of each type is allowed within an ACL.</para> 1355 1356 <para><itemizedlist> 1357 <listitem> 1358 <para>ACL_USER_OBJ: the owner's access rights.</para> 1359 </listitem> 1360 1361 <listitem> 1362 <para>ACL_GROUP_OBJ: the owning group's access rights.</para> 1363 </listitem> 1364 1365 <listitem> 1366 <para>ACL_OTHER: everybody's access rights.</para> 1367 </listitem> 1368 </itemizedlist></para> 1369 1370 <para>The remaining entry types expand the traditional permissions 1371 model:</para> 1372 1373 <para><itemizedlist> 1374 <listitem> 1375 <para>ACL_USER: grants access rights to a certain user.</para> 1376 </listitem> 1377 1378 <listitem> 1379 <para>ACL_GROUP: grants access rights to a certain 1380 group.</para> 1381 </listitem> 1382 1383 <listitem> 1384 <para>ACL_MASK: limits the maximum access rights which can be 1385 granted by entries of type ACL_GROUP_OBJ, ACL_USER and 1386 ACL_GROUP. As the name suggests, this entry acts as a mask. 1387 Only one ACL_MASK entry is allowed per ACL. If an ACL contains 1388 ACL_USER or ACL_GROUP entries, an ACL_MASK entry must be 1389 present too, otherwise it is optional.</para> 1390 </listitem> 1391 </itemizedlist></para> 1392 1393 <para>In order to maintain compatibility with applications not aware 1394 of ACLs, Posix 1003.1e changes the semantics of system calls and 1395 utilities which retrieve or manipulate an objects UNIX permissions. 1396 In case an object only has a minimal ACL, the group permissions bits 1397 of the UNIX permissions correspond to the value of the ACL_GROUP_OBJ 1398 entry.</para> 1399 1400 <para>However, if the ACL also contains an ACL_MASK entry, the 1401 behavior of those system calls and utilities is different. The group 1402 permissions bits of the UNIX permissions correspond to the value of 1403 the ACL_MASK entry, i. e. calling "chmod g-w" will not only revoke 1404 write access for the group, but for all entities which have been 1405 granted write access by ACL_USER or ACL_GROUP entries.</para> 1406 </sect4> 1407 1408 <sect4> 1409 <title>Mapping POSIX ACLs to OS X ACLs</title> 1410 1411 <para>When a client wants to read an object's ACL, afpd maps it's 1412 Posix ACL onto an equivalent OS X ACL. Writing an object's ACL 1413 requires afpd to map an OS X ACL onto a Posix ACL. Due to 1414 architectural restrictions of Posix ACLs, it is usually impossible 1415 to find an exact mapping so that the result of the mapping process 1416 will be an approximation of the original ACL's semantic.</para> 1417 1418 <para><itemizedlist> 1419 <listitem> 1420 <para>afpd silently discard entries which deny a set of 1421 permissions because they they can't be represented within the 1422 Posix architecture. </para> 1423 </listitem> 1424 1425 <listitem> 1426 <para>As entries within Posix ACLs are unordered, it is 1427 impossible to preserve order.</para> 1428 </listitem> 1429 1430 <listitem> 1431 <para>Inheritance control is subject to severe limitations as 1432 well:<itemizedlist> 1433 <listitem> 1434 <para>Entries with the only_inherit flag set will only 1435 become part of the directory's default ACL.</para> 1436 </listitem> 1437 1438 <listitem> 1439 <para>Entries with at least one of the flags 1440 file_inherit, directory_inherit or limit_inherit set, 1441 will become part of the directory's access and default 1442 ACL, but the restrictions they impose on inheritance 1443 will be ignored.</para> 1444 </listitem> 1445 </itemizedlist></para> 1446 </listitem> 1447 1448 <listitem> 1449 <para>The lack of a fine-granular permission model on the 1450 Posix side will normally result in an increase of granted 1451 permissions.</para> 1452 </listitem> 1453 </itemizedlist></para> 1454 1455 <para>As OS X clients aren't aware of the Posix 1003.1e specific 1456 relationship between UNIX permissions and ACL_MASK, afpd does not 1457 expose this feature to the client to avoid compatibility issues and 1458 handles *unix permissions and ACLs the same way as Apple's reference 1459 implementation of AFP does. When an object's UNIX permissions are 1460 requested, afpd calculates proper group rights and returns the 1461 result together with the owner's and everybody's access rights to 1462 the caller via "permissions" and "ua_permissions" members of the 1463 FPUnixPrivs structure (see Apple Filing Protocol Reference, page 1464 181). Changing an object's permissions, afpd always updates 1465 ACL_USER_OBJ, ACL_GROUP_OBJ and ACL_OTHERS. If an ACL_MASK entry is 1466 present too, afpd recalculates it's value so that the new group 1467 rights become effective and existing entries of type ACL_USER or 1468 ACL_GROUP stay intact.</para> 1469 </sect4> 1470 </sect3> 1471 </sect2> 1472 1473 <sect2 id="fce"> 1474 <title>Filesystem Change Events<indexterm> 1475 <primary>FCE</primary> 1476 </indexterm></title> 1477 1478 <para>Netatalk includes a nifty filesystem change event mechanism where 1479 afpd processes notfiy interested listeners about certain filesystem 1480 event by UDP network datagrams.</para> 1481 1482 <para>For the format of the UDP packets and for an example C application 1483 that demonstrates how to use these in a listener, take a look at the 1484 Netatalk sourcefile <filename>bin/misc/fce.c</filename>.</para> 1485 1486 <para>The currently supported FCE events are<itemizedlist> 1487 <listitem> 1488 <para>file modification (fmod)</para> 1489 </listitem> 1490 1491 <listitem> 1492 <para>file deletion (fdel)</para> 1493 </listitem> 1494 1495 <listitem> 1496 <para>directory deletion (ddel)</para> 1497 </listitem> 1498 1499 <listitem> 1500 <para>file creation (fcre)</para> 1501 </listitem> 1502 1503 <listitem> 1504 <para>directory deletion (ddel)</para> 1505 </listitem> 1506 </itemizedlist></para> 1507 1508 <para>For details on the available simple configuration options take a 1509 look at <filename><link 1510 linkend="fceconf">afp.conf</link></filename>.</para> 1511 </sect2> 1512 </sect1> 1513 1514 <sect1> 1515 <title>Starting and stopping Netatalk</title> 1516 1517 <para>The Netatalk distribution comes with several operating system 1518 specific startup script templates that are tailored according to the 1519 options given to the "configure" script before compiling. Currently, 1520 templates are provided for RedHat (sysv style), RedHat (systemd style), 1521 SUSE (sysv style), SUSE (systemd style), Gentoo, NetBSD, Debian and 1522 Solaris. You can select to install the generated startup script(s) 1523 <indexterm> 1524 <primary>Startscript</primary> 1525 1526 <secondary>startup script</secondary> 1527 </indexterm> by specifying a system type to "configure". To 1528 automatically install startup scripts give one of the available 1529 <option>--with-init-style</option> option to "configure".</para> 1530 1531 <para>Since new releases of Linux distributions appear all the time and 1532 the startup procedure for the other systems mentioned above might change 1533 as well, it is probably a good idea to not blindly install a startup 1534 script but to look at it first to see if it will work on your system. If 1535 you use Netatalk as part of a fixed setup, like a Linux distribution, an 1536 RPM or a BSD package, things will probably have been arranged properly for 1537 you. The following therefore applies mostly for people who have compiled 1538 Netatalk themselves.</para> 1539 1540 <para>The following daemon need to be started by whatever startup script 1541 mechanism is used:</para> 1542 1543 <itemizedlist> 1544 <listitem> 1545 <para>netatalk<indexterm> 1546 <primary>netatalk</primary> 1547 </indexterm></para> 1548 </listitem> 1549 </itemizedlist> 1550 1551 <para>Additionally, make sure that the configuration file 1552 <filename>afp.conf</filename> is in the right place.</para> 1553 </sect1> 1554</chapter> 1555