Skip to content

Dev Docs Arch Overview

Jump to bottom Edit New page
Andy Lemin edited this page Aug 16, 2025 · 2 revisions

WIP - ALL LINKS IN THIS WIKI STRUCTURE ARE CURRENTLY BROKEN DURING WIKI MIGRATION

THESE ARE COMMUNITY DOCS

Netatalk Architecture Overview

System Architecture

Netatalk implements a multi-layered architecture that provides Apple Filing Protocol (AFP) services to Mac clients while integrating seamlessly with Unix filesystem semantics.

Implementation Files:

  • Master Daemon: etc/netatalk/netatalk.c - Service coordinator and configuration manager
  • AFP Daemon: etc/afpd/main.c - Core AFP protocol server implementation
  • CNID Services: etc/cnid_metad/cnid_metad.c - CNID metadata management daemon
  • Database Backend: etc/cnid_dbd/main.c - Berkeley DB backend daemon
  • AppleTalk Support: etc/atalkd/main.c - AppleTalk protocol daemon
  • Build Integration: meson.build - Complete build system and service coordination
graph TB
    subgraph "Client Layer"
        A[Mac Clients] --> B[AFP Protocol]
    end
    
    subgraph "Protocol Layer"
        B --> C[DSI over TCP/IP]
        B --> D[ASP over AppleTalk]
    end
    
    subgraph "Core Services"
        C --> E[afpd - AFP Daemon]
        D --> E
        E --> F[Volume Management]
        E --> G[Authentication]
        E --> H[File Operations]
    end
    
    subgraph "Supporting Services"
        I[netatalk - Master Daemon]
        J[cnid_metad - CNID Metadata]
        K[cnid_dbd - Database Backend]
        L[atalkd - AppleTalk Daemon]
        M[Spotlight Integration]
    end
    
    subgraph "Storage Layer"
        N[Unix Filesystem]
        O[Berkeley DB]
        P[Extended Attributes]
    end
    
    I --> E
    J --> K
    K --> O
    E --> N
    E --> P
    E --> M
Loading

Core Data Structures

AFPObj - Central Connection Object

The AFPObj structure (defined in include/atalk/globals.h) serves as the central management object for AFP connections:

Implementation Files:

  • Structure Definition: include/atalk/globals.h - Complete AFPObj structure and related types
  • Connection Management: etc/afpd/afp_options.c - AFPObj initialization and configuration
  • Session Handling: etc/afpd/main.c - AFPObj lifecycle management and cleanup
typedef struct AFPObj {
    char *cmdlineconfigfile;
    int cmdlineflags;
    int proto;                    // AFPPROTO_DSI or AFPPROTO_ASP
    const void *signature;
    struct DSI *dsi;             // DSI connection handle
    void *handle;
    struct afp_options options;  // Comprehensive configuration
    dictionary *iniconfig;       // Configuration dictionary
    char username[MAXUSERLEN];   // Connected user
    uid_t uid, euid;            // User IDs
    int afp_version;            // AFP protocol version
    struct sl_ctx *sl_ctx;      // Spotlight context
    // ... additional fields for authentication, IPC, etc.
} AFPObj;

Configuration Architecture

The afp_options structure provides extensive configuration control:

  • Connection Management: Max connections, timeouts, buffer sizes
  • Protocol Support: DSI/ASP protocol selection, quantum sizes
  • Security Options: Authentication paths, Kerberos configuration
  • Feature Flags: Spotlight, ACLs, D-Bus integration
  • Performance Tuning: Directory cache size, splice operations
  • Database Configuration: CNID backend selection (Berkeley DB, MySQL, SQLite)

Implementation Files:

  • Configuration Parsing: etc/afpd/afp_config.c - Main configuration file parsing and validation
  • Options Processing: etc/afpd/afp_options.c - Command-line and configuration option handling
  • INI Parser: libatalk/iniparser/ - Configuration file format parsing library
  • Global Config: libatalk/util/netatalk_conf.c - Global configuration management

Core Design Principles

1. Separation of Concerns

  • Protocol Handling: Clear separation between AFP protocol logic and filesystem operations
  • Service Management: Master daemon coordinates all child services
  • Data Persistence: Dedicated CNID system manages file identification independently

Implementation Files:

  • AFP Protocol Layer: etc/afpd/afp_*.c - Protocol command implementations
  • Filesystem Layer: etc/afpd/file.c, etc/afpd/directory.c - Unix filesystem interface
  • Volume Management: etc/afpd/volume.c - Volume abstraction and mounting

2. Process Architecture

  • Master Process (netatalk): Service coordinator and configuration manager
  • Worker Processes (afpd): Handle individual client connections
  • Database Processes (cnid_metad, cnid_dbd): Manage persistent file metadata
  • Protocol Processes (atalkd): Handle AppleTalk networking stack

Implementation Files:

  • Process Management: etc/netatalk/netatalk.c - Master daemon and child process coordination
  • Connection Handling: etc/afpd/main.c - Client connection management and forking
  • Database Services: etc/cnid_metad/cnid_metad.c - Metadata daemon service management
  • IPC Communication: libatalk/util/server_ipc.c - Inter-process communication primitives

3. Multi-Protocol Support

  • Modern Clients: AFP over TCP/IP via DSI (Data Stream Interface)
  • Legacy Clients: AFP over AppleTalk via ASP (AppleTalk Session Protocol)
  • Concurrent Operation: Both protocols can operate simultaneously

Implementation Files:

  • DSI Protocol: libatalk/dsi/ - Data Stream Interface implementation
  • ASP Protocol: libatalk/asp/ - AppleTalk Session Protocol implementation
  • Protocol Selection: etc/afpd/main.c - Protocol detection and initialization

Protocol Implementation Details

AFP Command Set

The system implements a comprehensive AFP command set (from include/atalk/afp.h):

Core File Operations:

  • File Management: AFP_CREATEFILE, AFP_DELETE, AFP_RENAME, AFP_COPYFILE
  • Directory Operations: AFP_CREATEDIR, AFP_ENUMERATE, AFP_OPENDIR
  • Fork Operations: AFP_OPENFORK, AFP_READ, AFP_WRITE, AFP_FLUSH

Advanced Features:

  • Extended Operations: AFP_READ_EXT, AFP_WRITE_EXT (AFP 3.0+)
  • Catalog Search: AFP_CATSEARCH, AFP_CATSEARCH_EXT
  • Access Control: AFP_GETACL, AFP_SETACL (AFP 3.2+)
  • Extended Attributes: AFP_GETEXTATTR, AFP_SETEXTATTR
  • Spotlight Integration: AFP_SPOTLIGHT_PRIVATE

Implementation Files:

  • Protocol Definitions: include/atalk/afp.h - Complete AFP command and constant definitions
  • Command Dispatch: etc/afpd/afp_options.c - AFP command routing and processing
  • File Operations: etc/afpd/file.c - File management command implementations
  • Directory Operations: etc/afpd/directory.c - Directory management implementations
  • Fork Operations: etc/afpd/fork.c - Data/resource fork handling
  • Extended Features: etc/afpd/extattrs.c - Extended attribute support
  • Spotlight Commands: etc/afpd/spotlight*.c - Spotlight search integration

Server Capability Flags

The implementation supports advanced server features:

#define AFPSRVRINFO_COPY         (1<<0)   // Supports copyfile
#define AFPSRVRINFO_SRVUTF8      (1<<9)   // UTF8 names (AFP 3.1)
#define AFPSRVRINFO_UUID         (1<<10)  // UUIDs support
#define AFPSRVRINFO_EXTSLEEP     (1<<11)  // Extended sleep
#define AFPSRVRINFO_FASTBOZO     (1<<15)  // Fast copying

Configuration System Architecture

The system uses a sophisticated INI-based configuration:

#define INISEC_GLOBAL "global"
#define INISEC_HOMES  "homes"

// Macro-based configuration access
#define INIPARSER_GETSTR(config, section, key, default)
#define INIPARSER_GETSTRDUP(config, section, key, default)

Implementation Files:

  • INI Processing: libatalk/iniparser/iniparser.c - Core INI file parsing engine
  • Configuration Structure: etc/afpd/afp_config.c - Configuration validation and processing
  • Section Handling: libatalk/iniparser/dictionary.c - Configuration dictionary management
  • Macro System: include/atalk/iniparser.h - Configuration access macro definitions

Protocol Stack Architecture

AFP over TCP/IP (Modern)

+---------------------+
|   AFP Protocol      |  <- Application layer file operations
+---------------------+
|   DSI (Data         |  <- Session management and framing
|   Stream Interface) |
+---------------------+
|      TCP            |  <- Reliable transport
+---------------------+
|      IP             |  <- Network routing
+---------------------+
| Network Interface   |  <- Physical layer
+---------------------+

AFP over AppleTalk (Legacy)

+---------------------+
|   AFP Protocol      |  <- Application layer file operations
+---------------------+
|   ASP (AppleTalk    |  <- Session management
|   Session Protocol) |
+---------------------+
| ATP/RTMP/NBP/ZIP    |  <- AppleTalk transport protocols
+---------------------+
|   DDP (Datagram     |  <- AppleTalk network layer
|   Delivery Protocol)|
+---------------------+
| Network Interface   |  <- Physical layer
+---------------------+

Component Interaction Patterns

Service Lifecycle Management

  1. Startup Sequence:

    • netatalk master daemon starts
    • Configuration parsed and validated
    • Database services (cnid_metad) launched
    • Network services (afpd, atalkd) initialized
    • Service discovery (Bonjour/Avahi) activated

  2. Client Connection Handling:

    • Client connects to afpd listener
    • Authentication performed via UAM modules
    • Worker process forked for connection
    • Volume access established
    • File operations processed

  3. Graceful Shutdown:

    • SIGTERM sent to master process
    • Client connections gracefully closed
    • Database transactions committed
    • Child processes terminated
    • Resources cleaned up

Data Flow Architecture

sequenceDiagram
    participant Client as Mac Client
    participant afpd as AFP Daemon
    participant cnid as CNID System
    participant fs as Filesystem
    participant db as Berkeley DB
    
    Client->>afpd: File Operation Request
    afpd->>cnid: Get/Create CNID
    cnid->>db: Database Lookup
    db-->>cnid: CNID Data
    cnid-->>afpd: File Identifier
    afpd->>fs: Filesystem Operation
    fs-->>afpd: Operation Result
    afpd->>cnid: Update Metadata (if needed)
    afpd-->>Client: Response
Loading

Implementation-Specific Features

Directory Caching System

#define DEFAULT_MAX_DIRCACHE_SIZE 8192

The system implements intelligent directory caching with configurable size limits for performance optimization.

Optional Feature Support

The architecture supports conditional compilation of features:

#define OPTION_SPOTLIGHT     (1 << 13) // Spotlight search integration
#define OPTION_SPOTLIGHT_VOL (1 << 14) // Per-volume Spotlight control
#define OPTION_DDP          (1 << 17) // AppleTalk/DDP support
#define OPTION_DBUS_AFPSTATS (1 << 12) // D-Bus statistics interface

Unicode and Character Set Conversion System

Netatalk implements a sophisticated character conversion system (from include/atalk/unicode.h - 166 lines):

Core Character Set Types

// Primary character sets supported
typedef enum {
    CH_UCS2 = 0,        // Universal Character Set (16-bit)
    CH_UTF8 = 1,        // UTF-8 encoding
    CH_MAC = 2,         // Mac character encoding
    CH_UNIX = 3,        // Unix/Linux character encoding
    CH_UTF8_MAC = 4     // UTF-8 Mac variant (decomposed)
} charset_t;

#define NUM_CHARSETS 5  // Total supported character sets

Character Conversion Capabilities

// Conversion flags for comprehensive character handling
#define CONV_IGNORE         (1<<0)   // Ignore unconvertible characters
#define CONV_ESCAPEHEX      (1<<1)   // Escape with :[UCS2HEX] format
#define CONV_ESCAPEDOTS     (1<<2)   // Escape leading dots with :2600
#define CONV_PRECOMPOSE     (1<<6)   // Unicode precomposition (é -> é)
#define CONV_DECOMPOSE      (1<<7)   // Unicode decomposition (é -> e + ´)
#define CONV_TOUPPER        (1<<4)   // Convert to uppercase
#define CONV_TOLOWER        (1<<5)   // Convert to lowercase

// Character set capability flags
#define CHARSET_PRECOMPOSED 4        // Supports precomposed Unicode
#define CHARSET_DECOMPOSED  8        // Supports decomposed Unicode
#define CHARSET_MULTIBYTE   16       // Multi-byte character set
#define CHARSET_WIDECHAR    32       // Wide character support

Pluggable Character Set Architecture

// Character conversion function interface (pluggable design)
struct charset_functions {
    const char *name;                    // Character set name
    const long kTextEncoding;            // Mac TextEncoding constant
    size_t (*pull)(void *, char **inbuf, size_t *inbytesleft,
                   char **outbuf, size_t *outbytesleft);
    size_t (*push)(void *, char **inbuf, size_t *inbytesleft,
                   char **outbuf, size_t *outbytesleft);
    uint32_t flags;                      // Capability flags
    struct charset_functions *prev, *next; // Linked list
};

Key features:

  • Universal Conversion: All character sets convert through UCS2 intermediate format
  • Unicode Normalization: Full precomposition/decomposition support (critical for Mac compatibility)
  • Character Escaping: Safe handling of problematic characters via hex encoding
  • Case Folding: Configurable case handling for different filesystems
  • Multi-Byte Support: Complete support for Asian languages and complex scripts

Multi-Database Backend Support

  • Berkeley DB: Primary CNID backend
  • MySQL: Alternative relational backend (cnid_mysql_* configuration)
  • SQLite: Lightweight embedded option

DTrace Integration

When compiled with DTrace support, the system provides comprehensive tracing:

#define AFP_AFPFUNC_START(a,b)  // Function entry tracing
#define AFP_CNID_START(a)       // CNID operation tracing
#define AFP_READ_START(a)       // Read operation tracing
#define AFP_WRITE_START(a)      // Write operation tracing

Scalability Considerations

Connection Management

  • Process-per-connection: Each client gets dedicated afpd worker
  • Connection pooling: Master process manages worker lifecycle
  • Resource limits: Configurable limits prevent resource exhaustion

Database Performance

  • Centralized CNID: Single database instance per volume
  • Transaction batching: Efficient metadata updates
  • Index optimization: Berkeley DB tuned for AFP access patterns

Memory Management

  • Shared libraries: Common code shared across processes
  • Memory mapping: Efficient large file handling
  • Buffer management: Optimized I/O operations

Security Architecture

Authentication Flow

graph LR
    A[Client] --> B[AFP Login]
    B --> C{Auth Method}
    C -->|DHX/DHX2| D[Encrypted Challenge]
    C -->|PAM| E[System Auth]
    C -->|Kerberos| F[GSSAPI]
    C -->|Guest| G[Anonymous]
    D --> H[Session Established]
    E --> H
    F --> H
    G --> H
Loading

Access Control

  • Unix Permissions: Standard filesystem ACLs
  • AFP Permissions: Mac-specific access controls
  • Volume-level Security: Per-volume access restrictions
  • Network Security: IP-based access controls

Extension Points

User Authentication Modules (UAMs)

  • Pluggable Architecture: Dynamic loading of auth modules
  • Standard Modules: DHX, DHX2, PAM, Guest, Randnum
  • Custom Extensions: Support for organization-specific auth

Volume Plugins

  • Filesystem Abstraction: Support for different storage backends
  • Metadata Handling: Extensible attribute systems
  • Quota Management: Pluggable quota enforcement

Protocol Extensions

  • Spotlight Search: GNOME Tracker integration
  • Time Machine: Backup service support
  • Custom AFP Extensions: Organization-specific features

Core System Infrastructure

Logging System Architecture

The comprehensive logging system (include/atalk/logger.h, 164 lines) provides multi-level, multi-type logging with flexible output destinations and configuration:

Log Levels (11 levels)

enum loglevels {
    log_none,       // No logging
    log_severe,     // Critical system failures
    log_error,      // Error conditions
    log_warning,    // Warning messages
    log_note,       // Important notices
    log_info,       // Informational messages
    log_debug,      // Debug information
    log_debug6,     // Extended debug levels
    log_debug7,     // (debug6-debug9 for
    log_debug8,     // increasingly verbose
    log_debug9,     // debugging output)
    log_maxdebug    // Maximum verbosity
};

Log Types (11 specialized types)

enum logtypes {
    logtype_default,  // Default system logging
    logtype_logger,   // Logger subsystem
    logtype_cnid,     // CNID database system
    logtype_afpd,     // AFP daemon
    logtype_dsi,      // DSI protocol layer
    logtype_atalkd,   // AppleTalk daemon
    logtype_papd,     // Printer Access Protocol daemon
    logtype_uams,     // User Authentication Modules
    logtype_fce,      // File Change Events
    logtype_ad,       // AppleDouble metadata
    logtype_sl        // Spotlight search
};

Configuration Structures

// Main logging configuration
typedef struct {
    bool inited;                  // File log initialized?
    bool syslog_opened;          // Syslog connection open?
    bool console;                // Console output enabled?
    char processname[16];        // Process name for logging
    int syslog_facility;         // Syslog facility code
    int syslog_display_options;  // Display option flags
} log_config_t;

// Per-type logging configuration
typedef struct {
    bool set;                    // Individual configuration?
    bool syslog;                // Log to syslog?
    int fd;                     // Log file descriptor
    enum loglevels level;       // Minimum log level
    int display_options;        // Display formatting options
    bool timestamp_us;          // Microsecond timestamps?
} logtype_conf_t;

Spotlight Search Integration

The Spotlight system (include/atalk/spotlight.h, 160 lines) provides advanced search capabilities using Tracker/TinySPARQL backends with complete query state management:

RPC Command Structure

#define SPOTLIGHT_CMD_OPEN    1   // Open search session
#define SPOTLIGHT_CMD_FLAGS   2   // Set search flags
#define SPOTLIGHT_CMD_RPC     3   // Execute RPC call
#define SPOTLIGHT_CMD_OPEN2   4   // Extended open session

Data Type System

typedef DALLOC_CTX     sl_array_t;     // Dynamic arrays
typedef DALLOC_CTX     sl_dict_t;      // Key/value dictionaries
typedef DALLOC_CTX     sl_filemeta_t;  // File metadata containers
typedef int            sl_nil_t;       // Null values
typedef bool           sl_bool_t;      // Boolean values
typedef struct timeval sl_time_t;      // Timestamp values
typedef struct {
    char sl_uuid[16];                  // 128-bit UUID
} sl_uuid_t;
typedef struct {
    uint16_t   ca_unkn1;              // Unknown field
    uint32_t   ca_context;            // Search context
    DALLOC_CTX *ca_cnids;             // CNID array
} sl_cnids_t;

Query State Machine (8 states)

The Spotlight search system implements a sophisticated 8-state query state machine for handling asynchronous search operations:

typedef enum {
    SLQ_STATE_NEW,            // Query received from client
    SLQ_STATE_RUNNING,        // Query dispatched to Tracker
    SLQ_STATE_RESULTS,        // Reading async results
    SLQ_STATE_FULL,           // Result queue is full
    SLQ_STATE_DONE,           // All results received
    SLQ_STATE_CANCEL_PENDING, // Cancel operation pending
    SLQ_STATE_CANCELLED,      // Query cancelled
    SLQ_STATE_ERROR           // Error occurred
} slq_state_t;
stateDiagram-v2
    [*] --> NEW
    NEW --> RUNNING: Dispatch to Tracker/TinySPARQL
    RUNNING --> RESULTS: Results Available
    RESULTS --> FULL: Queue Full
    FULL --> RESULTS: Queue Space Available
    RESULTS --> DONE: All Results Retrieved
    RUNNING --> DONE: Query Complete
    NEW --> CANCEL_PENDING: Cancel Request
    RUNNING --> CANCEL_PENDING: Cancel Request
    RESULTS --> CANCEL_PENDING: Cancel Request
    FULL --> CANCEL_PENDING: Cancel Request
    CANCEL_PENDING --> CANCELLED: Cancel Complete
    NEW --> ERROR: Query Error
    RUNNING --> ERROR: Tracker Error
    RESULTS --> ERROR: Processing Error
    FULL --> ERROR: Buffer Error
    DONE --> [*]
    CANCELLED --> [*]
    ERROR --> [*]
Loading

Spotlight Query Processing Flow

sequenceDiagram
    participant Client as Mac Client
    participant AFP as afpd
    participant SL as Spotlight Layer
    participant Tracker as Tracker/TinySPARQL
    participant FS as Filesystem
    
    Client->>AFP: Spotlight Search Request
    AFP->>SL: Create slq_t query object
    SL->>SL: Set state = SLQ_STATE_NEW
    SL->>Tracker: Dispatch SPARQL query
    SL->>SL: Set state = SLQ_STATE_RUNNING
    
    loop Async Result Processing
        Tracker->>FS: Index search
        FS-->>Tracker: File metadata
        Tracker->>SL: Results available
        SL->>SL: Set state = SLQ_STATE_RESULTS
        
        alt Result queue full
            SL->>SL: Set state = SLQ_STATE_FULL
            SL->>Client: Partial results
            Client->>SL: Request more
            SL->>SL: Set state = SLQ_STATE_RESULTS
        else All results retrieved
            SL->>SL: Set state = SLQ_STATE_DONE
        end
    end
    
    SL->>AFP: Final results
    AFP->>Client: Spotlight response
    SL->>SL: Cleanup query object
Loading

Query Management Structure (139 lines)

typedef struct _slq_t {
    struct list_head  slq_list;      // Query list linkage
    slq_state_t       slq_state;     // Current state
    AFPObj           *slq_obj;       // Global AFP object
    const struct vol *slq_vol;       // Target volume
    char             *slq_scope;     // Search scope path
    time_t            slq_time;      // Query timestamp
    uint64_t          slq_ctx1;      // Client context 1
    uint64_t          slq_ctx2;      // Client context 2
    sl_array_t       *slq_reqinfo;   // Requested metadata
    const char       *slq_qstring;   // Spotlight query string
    uint64_t         *slq_cnids;     // CNID array
    size_t            slq_cnids_num; // CNID array size
    void             *tracker_cursor; // SPARQL cursor
    bool              slq_allow_expr; // Expression support
    uint64_t          slq_result_limit; // Result limitation
    struct sl_rslts  *query_results; // Query results
} slq_t;

Process Communication Architecture

Netatalk implements a sophisticated multi-process architecture with comprehensive IPC mechanisms:

graph TB
    subgraph "Master Process Domain"
        Master["netatalk master<br/>PID management & coordination"]
        ConfigMgr["Configuration Manager<br/>Config file parsing"]
        ServiceCoord["Service Coordinator<br/>Process lifecycle"]
    end
    
    subgraph "Worker Process Domain"
        AFP1["afpd worker 1<br/>Client connections"]
        AFP2["afpd worker 2<br/>Client connections"]
        AFPN["afpd worker N<br/>Client connections"]
        
        CNID_Meta["cnid_metad<br/>Metadata coordinator"]
        CNID_DB["cnid_dbd<br/>Berkeley DB interface"]
        
        Spotlight["Spotlight daemon<br/>Search indexing"]
        TimeMachine["Time Machine support<br/>Backup coordination"]
    end
    
    subgraph "IPC Mechanisms"
        UnixSockets["Unix Domain Sockets<br/>Command/response"]
        SharedMem["Shared Memory<br/>Configuration cache"]
        Signals["POSIX Signals<br/>Lifecycle control"]
        SemMutex["Semaphores/Mutexes<br/>Resource coordination"]
        FIFOs["Named FIFOs<br/>Event notifications"]
    end
    
    subgraph "External Integrations"
        SystemD["systemd integration<br/>Service management"]
        PAM["PAM modules<br/>Authentication"]
        Kerberos["Kerberos KDC<br/>Single sign-on"]
        LDAP["LDAP directories<br/>User databases"]
        Tracker["Tracker/TinySPARQL<br/>Full-text search"]
    end
    
    Master --> ConfigMgr
    Master --> ServiceCoord
    ServiceCoord --> AFP1
    ServiceCoord --> AFP2
    ServiceCoord --> AFPN
    ServiceCoord --> CNID_Meta
    ServiceCoord --> Spotlight
    
    AFP1 -.-> UnixSockets
    AFP2 -.-> UnixSockets
    AFPN -.-> UnixSockets
    CNID_Meta -.-> UnixSockets
    CNID_DB -.-> UnixSockets
    
    Master -.-> SharedMem
    ConfigMgr -.-> SharedMem
    AFP1 -.-> SharedMem
    AFP2 -.-> SharedMem
    
    Master -.-> Signals
    ServiceCoord -.-> Signals
    AFP1 -.-> Signals
    AFP2 -.-> Signals
    CNID_Meta -.-> Signals
    
    CNID_Meta --> CNID_DB
    AFP1 --> CNID_Meta
    AFP2 --> CNID_Meta
    AFPN --> CNID_Meta
    
    Spotlight -.-> Tracker
    AFP1 -.-> PAM
    AFP2 -.-> PAM
    Master -.-> SystemD
    
    subgraph "Communication Patterns"
        CP1["Request/Response: AFP ↔ CNID"]
        CP2["Event Broadcasting: Config changes"]
        CP3["Resource Locking: Database access"]
        CP4["Health Monitoring: Process status"]
        CP5["Load Balancing: Connection distribution"]
    end
Loading

IPC Implementation Details

// Master process coordination structure
struct netatalk_master {
    pid_t           master_pid;         // Master process ID
    int             config_fd;          // Configuration socket
    int             signal_fd;          // Signal handling socket
    sem_t           *config_sem;        // Configuration semaphore
    void            *shared_config;     // Shared configuration memory
    struct afp_child_map *children;     // Child process mapping
};

// Worker process communication
struct afp_child {
    pid_t           child_pid;          // Worker process ID
    int             ipc_fd;             // IPC socket to master
    int             client_count;       // Active client connections
    time_t          last_heartbeat;     // Last health check
    uint32_t        capabilities;       // Process capabilities
};

// CNID IPC message structure
struct cnid_dbd_rqst {
    int             op;                 // Operation code
    cnid_t          cnid;               // File CNID
    dev_t           dev;                // Device number
    ino_t           ino;                // Inode number
    uint32_t        type;               // File type
    uint32_t        did;                // Directory ID
    char            *name;              // Filename
    size_t          namelen;            // Name length
};

Utility Functions Architecture

The comprehensive utility system (include/atalk/util.h, 248 lines) provides essential infrastructure for networking, locking, process management, and system operations:

Error Handling System

// Exit error codes
#define EXITERR_CLNT 1    // Client-related error
#define EXITERR_CONF 2    // Configuration error
#define EXITERR_SYS  3    // System error
#define EXITERR_CLOSED 4  // Connection immediately closed

// Panic and assertion macros
#define AFP_PANIC(why) do { netatalk_panic(why); abort(); } while(0);
#define AFP_ASSERT(b) do { if (!(b)) { AFP_PANIC(#b); } } while(0);

Network Utilities

// Endian conversion for 64-bit values
#ifdef WORDS_BIGENDIAN
#define hton64(x) (x)
#define ntoh64(x) (x)
#else
#define hton64(x) ((uint64_t)(htonl(((x) >> 32) & 0xffffffffLL)) | \
                   (uint64_t)((htonl(x) & 0xffffffffLL) << 32))
#define ntoh64(x) (hton64(x))
#endif

Socket Event Management

enum asev_fdtype { IPC_FD, LISTEN_FD };

struct asev_data {
    enum asev_fdtype fdtype;  // File descriptor type
    void            *private; // AFPconfig or afp_child_t pointer
    int             protocol; // ASP or DSI protocol
};

struct asev {
    struct pollfd    *fdset; // poll() file descriptor array
    struct asev_data *data;  // Associated data array
    int              max;    // Maximum descriptors
    int              used;   // Currently used descriptors
};

File Locking Interface

// Locking macros built on lock_reg()
#define read_lock(fd, offset, whence, len) \
    lock_reg((fd), F_SETLK, F_RDLCK, (offset), (whence), (len))
#define write_lock(fd, offset, whence, len) \
    lock_reg((fd), F_SETLK, F_WRLCK, (offset), (whence), (len))
#define unlock(fd, offset, whence, len) \
    lock_reg((fd), F_SETLK, F_UNLCK, (offset), (whence), (len))

Dynamic Module Loading

  • Cross-platform dlopen support: NetBSD, OpenBSD, and standard implementations
  • mod_open/mod_close: Dynamic library management
  • mod_symbol: Symbol resolution from loaded modules
  • Conditional compilation: Platform-specific loading strategies

Performance Characteristics

Optimizations

  • Zero-copy I/O: Sendfile and splice system calls
  • Asynchronous Operations: Event-driven networking via libevent
  • Efficient Metadata: Optimized AppleDouble format handling
  • Connection Multiplexing: Efficient TCP connection reuse

Monitoring Points

  • Connection Statistics: Active sessions and throughput
  • Database Performance: CNID operation metrics
  • Resource Usage: Memory and CPU utilization
  • Error Rates: Protocol and filesystem error tracking

This architecture provides a solid foundation for understanding how Netatalk components interact to deliver reliable AFP services while maintaining compatibility across different Mac generations and network configurations.

Add a custom footer

Resources

OS Specific Guides

Tech Notes

Development

Clone this wiki locally