Dev Docs

Netatalk Project Developer Docs

Netatalk Project Developer Docs

These pages describe Netatalk’s source organization, data structures, and implementation contracts. They supplement the user manual and Doxygen docs.

Audited against Netatalk d63155e13 on 2026-10-10. This describes the current source checkout; older releases may differ. See the audit report for findings and verification limits.

What is Netatalk?

Netatalk is a Free and Open Source Apple Filing Protocol (AFP) server for Unix-like systems. It implements AFP versions through 3.4 over TCP/IP using DSI, with optional AFP-over-AppleTalk support for classic clients. Build and configuration choices determine which authentication, search, discovery, and platform features are available.

The netatalk controller supervises the afpd listener, which forks a worker for each client connection. Workers authenticate users, manage mounted volumes and open forks, and perform filesystem operations. They maintain private caches and access persistent CNID records through embedded SQLite (mandatory/default) or an optional MySQL backend. There is no Berkeley DB CNID backend or CNID daemon pair in this checkout; dbd remains an offline maintenance utility.

flowchart LR
    controller[netatalk controller] --> listener[afpd listener and IPC relay]
    client[AFP client] -->|DSI over TCP| listener
    listener -->|fork| worker[afpd session worker]
    worker --> storage[Filesystem and Mac metadata]
    worker --> cnid[SQLite or optional MySQL CNID]

The controller uses libevent or libev. The AFP parent uses poll() for listeners, child IPC, and optional afpstats requests. DSI workers poll the client socket, cache-hint pipe, and signal self-pipe; signal actions are deferred into the worker’s main loop. Ordinary cross-process cache hints are best effort and supplement filesystem validation.

Developer Docs Index

Page	Focus
Architecture Overview	Process model, source map, shared structures, and optional subsystems
Netatalk Configuration	Parsing, inheritance, defaults, aliases, and reload behavior
Netatalk Controller Daemon	Supervision, event libraries, discovery, and execution modes
AFP Daemon	Parent/worker loops, command dispatch, open forks, signals, and idle cleanup
libatalk API	Shared library interfaces, implementation locations, and ownership
Data Flow	Connection, mount, file I/O, metadata, notifications, and search paths
Caching Architecture	Directory, metadata, resource-fork, and parent-directory fd caches
Network Protocols	DSI/ASP framing, transport limits, streaming, and reconnect
AppleTalk Networking	Optional protocols, standalone services, and historical kernel sources
User Authentication	UAMs, PAM/GSSAPI, SRP credentials, identity mapping, and tokens
CNID Database System	SQLite/MySQL dispatch, persistent IDs, errors, resets, and maintenance
Shared Volumes	Volume lifecycle, access, metadata storage, and multi-protocol policy
Performance Tuning	Implemented controls, memory costs, tradeoffs, and measurement
Troubleshooting	Build/configuration checks, logs, diagnostics, and failure contracts
Virtual Icon	Synthesized volume icons and write/truncate materialization

Source Code Organization

Location	Responsibility
etc/afpd	AFP listener and workers, command handlers, caches, volume and fork management
etc/netatalk	Controller, service supervision, and Zeroconf registration
etc/uams	Dynamically loaded authentication modules
etc/spotlight	CNID, Localsearch, and Xapian search implementations
libatalk	Shared DSI/AppleTalk, AppleDouble, CNID, Unicode, VFS, ACL, and utility code
include/atalk	Shared structures and API declarations
bin	Utilities, including `dbd`, `nad`, and `afppasswd`
test	Unit tests, AFP command tests, integration scripts, fuzzing, and benchmarks
contrib	Additional utilities, services, scripts, and integrations
distrib	Packaging, platform service templates, and deployment examples
config	Installed configuration templates and PAM integration
doc	User manual, man pages, and developer documentation inputs
meson.build, meson_options.txt	Build targets, dependencies, feature selection, and defaults

Key Features and Implementation Boundaries

AFP and file storage: handlers in etc/afpd use DSI transport in libatalk/dsi. AppleDouble code in libatalk/adouble manages Mac metadata and resource forks; CNID code in libatalk/cnid manages persistent identity. Their storage and lifecycles are distinct.
Authentication: UAMs include DHX/DHX2, cleartext PAM/Unix variants, Kerberos/GSSAPI, guest, legacy Randnum, and SRP, subject to build availability. The default UAM list is uams_dhx2.so. LDAP supports UUID/name lookup for ACLs; it is not itself an AFP password-authentication module.
Search: optional Spotlight support selects a backend per volume: cnid (default), localsearch, or xapian. Their indexing and query models differ; only Localsearch requires the controller’s private D-Bus/indexer setup.
Time Machine and discovery: volume capability handling is in etc/afpd/volume.c; Bonjour/DNS-SD advertisements use Avahi or mDNSResponder through etc/netatalk/afp_zeroconf.c. Advertised capabilities and usable client features depend on configuration and client support.
Caching and transfers: workers use ARC/LRU directory caching, cached AppleDouble metadata, resource-fork content caching, and a parent-directory fd cache. Sendfile/recvfile paths depend on the build, platform, and selected storage. multi protocol adjusts coherency defaults for external writers.
Single-user mode: a restricted non-root server uses SRP, SQLite, and private user-owned state, and admits only the calling UID. Normal service mode runs with privilege changes after authentication. See the controller and authentication pages for validation requirements.
AppleTalk: optional userspace protocols and services require host-kernel AppleTalk support. atalkd, papd, timelord, a2boot, and macipgw have separate service scripts; the controller does not supervise them. The current Meson build installs compatibility headers from historical BSD kernel sources without building a kernel module.

Project Information and Contributing

The project is primarily C, with Meson selecting C11; the optional Xapian wrapper uses C++. Build details and platform feature detection are in meson.build. Bin scripts are Perl 5 strict, alternatively POSIX compatible shell scripts.

Consult COPYING, COPYRIGHT, and individual source headers for licensing terms.

Start with README.md for project/build information and test/README.md for the test layout and execution instructions. Repository documentation is under doc/manual, doc/manpages, and doc/developer, with Doxygen comments alongside implementations.

When changing behavior, update the relevant detailed page and its source links, record the source revision for changed defaults or contracts, and select existing tests appropriate to the affected subsystem. These pages document implemented behavior and known limits; they do not promise complete protocol coverage or universal performance results.

Footnotes

Generated from the Netatalk GitHub Wiki

Last updated 2026-10-21