Skip to content

Dev Docs Arch Protocols

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

Protocol Stack Documentation

Network Protocol Architecture

Netatalk supports two distinct network protocol stacks for AFP communication, allowing it to serve both modern and legacy Mac clients.

Implementation Files:

  • DSI Protocol: libatalk/dsi/ - Data Stream Interface implementation for TCP/IP
  • ASP Protocol: libatalk/asp/ - AppleTalk Session Protocol implementation
  • AppleTalk Stack: libatalk/atp/, etc/atalkd/ - AppleTalk transport and routing
  • Protocol Headers: include/atalk/dsi.h, include/atalk/asp.h - Protocol constants and structures

AFP over TCP/IP (DSI Protocol)

Data Stream Interface (DSI)

DSI is the session layer protocol that carries AFP over TCP/IP connections. It provides:

  • Session Management: Connection establishment and teardown
  • Request/Response Framing: Message boundaries and sequencing
  • Flow Control: Data streaming and buffering
  • Error Handling: Connection recovery and error reporting

Implementation Files:

  • Core DSI Implementation: libatalk/dsi/dsi_stream.c - Main DSI protocol engine
  • TCP Transport: libatalk/dsi/dsi_tcp.c - TCP socket handling and network I/O
  • Connection Management: libatalk/dsi/dsi_init.c - DSI session initialization and cleanup
  • Command Processing: libatalk/dsi/dsi_cmdreply.c - Command/reply message handling
  • Attention Handling: libatalk/dsi/dsi_attn.c - Server attention message processing

DSI Message Format

The DSI protocol uses a fixed 16-byte header for all messages:

Implementation Files:

  • Header Definitions: include/atalk/dsi.h - DSI message format constants and structures
  • Header Processing: libatalk/dsi/dsi_stream.c - DSI header parsing and construction
  • Network Byte Order: libatalk/dsi/dsi_tcp.c - Endianness handling for network transmission
#define DSI_BLOCKSIZ 16
struct dsi_block {
    uint8_t dsi_flags;       /* packet type: request or reply */
    uint8_t dsi_command;     /* command */
    uint16_t dsi_requestID;  /* request ID */
    union {
        uint32_t dsi_code;   /* error code */
        uint32_t dsi_doff;   /* data offset */
    } dsi_data;
    uint32_t dsi_len;        /* total data length */
    uint32_t dsi_reserved;   /* reserved field */
};

Header Layout (Network Byte Order):

DSI Header (16 bytes):
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|FL|CM|     REQUEST ID        |  DATA OFFSET/CODE |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|           TOTAL DATA LENGTH                     |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|                 RESERVED                        |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

FL = Flags: DSIFL_REQUEST (0x00) or DSIFL_REPLY (0x01)
CM = Command (1 byte)
REQUEST ID = Request identifier (2 bytes, network order)
DATA OFFSET/CODE = Data offset (requests) or error code (replies) (4 bytes)
TOTAL DATA LENGTH = Total message length (4 bytes, network order)
RESERVED = Reserved field (4 bytes)

DSI Commands

Command Value Description
DSIFUNC_CLOSE 1 Close the DSI session
DSIFUNC_CMD 2 AFP command request
DSIFUNC_STAT 3 Get server status
DSIFUNC_OPEN 4 Open new DSI session
DSIFUNC_TICKLE 5 Keep-alive message
DSIFUNC_WRITE 6 Write data to server
DSIFUNC_ATTN 8 Server attention message

DSI Error Codes

Error Value Description
DSIERR_OK 0x0000 Success
DSIERR_BADVERS 0xfbd6 Bad version
DSIERR_BUFSMALL 0xfbd5 Buffer too small
DSIERR_NOSESS 0xfbd4 No session
DSIERR_NOSERV 0xfbd3 No server
DSIERR_PARM 0xfbd2 Parameter error
DSIERR_SERVBUSY 0xfbd1 Server busy
DSIERR_SESSCLOS 0xfbd0 Session closed
DSIERR_SIZERR 0xfbcf Size error
DSIERR_TOOMANY 0xfbce Too many connections

DSI Session Options

Option Value Description
DSIOPT_SERVQUANT 0x00 Server request quantum
DSIOPT_ATTNQUANT 0x01 Attention quantum
DSIOPT_REPLCSIZE 0x02 AFP replaycache size

Quantum Configuration:

  • Default server quantum: 1MB (DSI_SERVQUANT_DEF = 0x100000L)
  • Minimum server quantum: 32KB (DSI_SERVQUANT_MIN = 32000)
  • Maximum server quantum: 4GB (DSI_SERVQUANT_MAX = 0xffffffff)
  • Default attention quantum: 2 (DSI_DEFQUANT = 2)

End-to-End Multi-Layer Buffering Architecture

The DSI implementation uses a sophisticated 4-layer buffering system from network to filesystem that is critical for performance and debugging:

Implementation Files:

  • Buffer Management: libatalk/dsi/dsi_stream.c - Core buffering logic and read-ahead management
  • Socket Buffers: libatalk/dsi/dsi_tcp.c - TCP socket buffer configuration (SO_RCVBUF/SO_SNDBUF)
  • DSI Buffers: include/atalk/dsi.h - DSI buffer structure definitions (DSI_DATASIZ, etc.)
  • Flow Control: libatalk/dsi/dsi_stream.c - dsi_peek() and buffer space management
  • Configuration: etc/afpd/afp_config.c - dsireadbuf and quantum configuration parsing
graph TB
    subgraph "Network Layer"
        A[TCP Socket Buffer<br/>Kernel managed]
        B[Socket Receive Buffer<br/>SO_RCVBUF]
        C[Socket Send Buffer<br/>SO_SNDBUF]
    end
    
    subgraph "DSI Stream Layer"
        D[DSI Read Buffer<br/>dsi->buffer to dsi->end<br/>Configurable via -dsireadbuf]
        E[DSI Command Buffer<br/>dsi->commands<br/>Receives DSI headers]
        F[DSI Data Buffer<br/>dsi->data array DSI_DATASIZ<br/>64KB reply buffer]
    end
    
    subgraph "DSI Buffer Management"
        G[Read-ahead Pointers<br/>start, eof, buffer, end]
        H[Quantum Control<br/>server_quantum: 32KB-4GB<br/>Default: 1MB]
        I[Flow Control<br/>dsi_peek and select logic]
    end
    
    subgraph "AFP Command Layer"
        J[AFP Command Processing<br/>afp_* functions]
        K[Volume Operations<br/>File/Directory operations]
    end
    
    subgraph "VFS/Filesystem"
        L[VFS Buffer Cache<br/>Kernel page cache]
        M[Disk I/O<br/>Physical storage]
    end
    
    A --> D
    B --> D
    D --> G
    G --> E
    E --> J
    J --> K
    K --> L
    L --> M
    
    F --> C
    C --> A
    
    H -.-> D
    H -.-> F
    I -.-> G
Loading

DSI Quantum Management and Flow Control Pipeline

The DSI layer implements sophisticated flow control to prevent buffer overruns and optimize performance:

sequenceDiagram
    participant Client as Mac Client
    participant TCP as TCP Layer
    participant DSI as DSI Stream Layer
    participant Buf as Buffer Manager
    participant AFP as AFP Layer
    
    Note over Client,AFP: DSI Session Establishment with Quantum Negotiation
    Client->>DSI: OpenSession (request quantum)
    DSI->>Client: Server Quantum: 1MB (default)
    
    Note over Client,AFP: Large File Transfer with Flow Control
    Client->>TCP: Large AFP Write Request
    TCP->>DSI: Data chunks
    DSI->>Buf: Check buffer space (dsi_peek)
    
    alt Buffer has space
        Buf->>DSI: Read into dsi->buffer
        DSI->>AFP: Process command
    else Buffer full (dsi->eof >= dsi->end)
        Buf->>DSI: Log "readahead buffer full"
        DSI->>Buf: Wait for space (select)
        Buf->>DSI: Buffer space available
    end
    
    AFP->>DSI: Response data
    DSI->>Buf: Fill reply buffer (64KB chunks)
    Buf->>TCP: Send via writev() coalescing
    TCP->>Client: Response chunks
    
    Note over DSI: TCP_NODELAY for small packets
    Note over Buf: Signal blocking during writes
Loading

Enhanced DSI State Machine with Buffer Integration

The DSI implementation maintains 9 sophisticated state flags that interact with buffer management:

stateDiagram-v2
    [*] --> Closed
    
    state "DSI Protocol States" as DSI {
        Closed --> Connected: TCP Connect
        Connected --> SessionOpen: DSI OpenSession
        SessionOpen --> DataReceived: DSI_DATA flag set
        DataReceived --> AFPRunning: DSI_RUNNING flag set
        AFPRunning --> DataReceived: More commands
    }
    
    state "Buffer Management States" as Buf {
        BufferEmpty --> BufferFilling: dsi_stream_read()
        BufferFilling --> BufferReady: Data available
        BufferReady --> BufferProcessing: AFP command
        BufferProcessing --> BufferEmpty: Command complete
        BufferReady --> BufferFull: dsi->eof >= dsi->end
        BufferFull --> BufferReady: Space available
    }
    
    state "Advanced Connection States" as Advanced {
        AFPRunning --> Sleeping: DSI_SLEEPING (FPZzz)
        AFPRunning --> ExtSleeping: DSI_EXTSLEEP
        AFPRunning --> NoReply: DSI_NOREPLY (streaming)
        AFPRunning --> Disconnected: DSI_DISCONNECTED
        AFPRunning --> Dying: DSI_DIE (SIGUSR1)
        AFPRunning --> LoggedOut: DSI_AFP_LOGGED_OUT
        AFPRunning --> Reconnecting: DSI_RECONSOCKET
        AFPRunning --> ReconInProgress: DSI_RECONINPROG
    }
    
    DSI --> Buf: Buffer operations
    DSI --> Advanced: State transitions
    
    Sleeping --> AFPRunning: Wake up
    ExtSleeping --> AFPRunning: Extended wake
    NoReply --> AFPRunning: Stream complete
    Disconnected --> [*]: Connection lost
    Dying --> [*]: Graceful shutdown
    LoggedOut --> Closed: Client logout
    Reconnecting --> AFPRunning: New socket
    ReconInProgress --> AFPRunning: Reconnect complete
Loading

Performance Optimization Architecture

The DSI implementation includes sophisticated optimizations critical for Mac client performance:

graph TB
    subgraph "Network Optimizations"
        A[TCP_NODELAY<br/>Disable Nagle algorithm<br/>Essential for Mac responsiveness]
        B[writev Coalescing<br/>Combine DSI header + data<br/>Reduce system calls]
        C[Socket Buffer Tuning<br/>SO_RCVBUF/SO_SNDBUF<br/>Match quantum sizes]
    end
    
    subgraph "DSI Buffer Optimizations"
        D[Read-ahead Buffering<br/>dsireadbuf configuration<br/>Prevents excessive reads]
        E[Quantum Management<br/>1MB default, 32KB-4GB range<br/>Network condition tuning]
        F[Zero-copy Pointers<br/>start/eof/end management<br/>Minimize data copying]
    end
    
    subgraph "Signal Safety Architecture"
        G[Atomic Write Protection<br/>SIG_BLOCK during transfers<br/>Prevents corruption]
        H[Tickle Suppression<br/>SIGALRM disabled during<br/>large file transfers]
        I[Attention Buffer Isolation<br/>Separate buffers for<br/>SIGHUP/SIGTERM handlers]
    end
    
    subgraph "AFP Layer Integration"
        J[Streaming Read Pipeline<br/>dsi_readinit/dsi_read<br/>Large file optimization]
        K[Partial Packet Handling<br/>dsi_write incomplete<br/>packet management]
        L[Sendfile Integration<br/>Zero-copy reads when<br/>available if compiled with sendfile support]
    end
    
    A --> D
    B --> E
    C --> F
    D --> G
    E --> H
    F --> I
    G --> J
    H --> K
    I --> L
Loading

Detailed Read/Write Pipeline with Buffer Flow

Shows the complete data path through all buffering layers for performance analysis:

sequenceDiagram
    participant Mac as Mac Client
    participant Net as TCP Network
    participant DSI as DSI Layer
    participant Buf as Buffer Manager
    participant Disk as Filesystem
    
    Note over Mac,Disk: Write Pipeline (Client → Server → Disk)
    
    Mac->>Net: AFP Write + Data Stream
    Net->>DSI: TCP segments
    DSI->>Buf: dsi_stream_receive()
    Buf->>DSI: Fill read-ahead buffer (dsireadbuf)
    DSI->>DSI: Parse 16-byte DSI header
    DSI->>Buf: dsi_writeinit(buflen, datasize)
    
    loop Transfer Loop (until datasize = 0)
        Buf->>DSI: dsi_write() - extract buffered data
        DSI->>Disk: Write data chunk to file
        Disk-->>DSI: Write acknowledgment
        DSI->>Buf: Update remaining datasize counter
    end
    
    DSI->>Buf: dsi_writeflush() - clear remaining buffers
    DSI->>Net: Send AFP success response
    Net->>Mac: Transfer complete
    
    Note over Mac,Disk: Read Pipeline (Server → Client)
    
    Mac->>DSI: AFP Read Request
    DSI->>Disk: Read file data
    Disk-->>DSI: File content
    DSI->>Buf: dsi_readinit() - setup streaming transfer
    DSI->>Net: Send DSI header + initial data
    
    loop Streaming Loop (quantum-limited)
        DSI->>Buf: dsi_read() - get next chunk
        Buf->>Net: Stream via quantum-sized chunks
        Net->>Mac: Data delivery
        DSI->>Buf: Update transfer progress
    end
    
    DSI->>Buf: dsi_readdone() - cleanup transfer state
Loading

TCP Connection Management

sequenceDiagram
    participant Client as Mac Client
    participant Server as afpd
    
    Client->>Server: TCP SYN (port 548)
    Server-->>Client: TCP SYN-ACK
    Client->>Server: TCP ACK
    
    Client->>Server: DSI OpenSession
    Server-->>Client: DSI OpenSession Reply
    
    loop AFP Operations
        Client->>Server: DSI Command (AFP Request)
        Server-->>Client: DSI Command Reply (AFP Response)
    end
    
    Client->>Server: DSI CloseSession
    Server-->>Client: DSI CloseSession Reply
    
    Client->>Server: TCP FIN
    Server-->>Client: TCP FIN-ACK
Loading

DSI Performance Tuning Guidelines

Critical Buffer Configuration

Read-ahead Buffer Size (-dsireadbuf option):

  • Default: System-dependent, typically 16KB-32KB
  • Recommended: Match or exceed server quantum (1MB default)
  • Symptoms of undersized buffer: "readahead buffer is full" log messages
  • Large file transfers: Increase to 2-4MB for optimal performance

Server Quantum Configuration:

  • Default: 1MB (DSI_SERVQUANT_DEF = 0x100000L)
  • Range: 32KB (DSI_SERVQUANT_MIN) to 4GB (DSI_SERVQUANT_MAX)
  • Network optimization: Match network MTU and latency characteristics
  • High-latency links: Increase quantum size to reduce round trips

Implementation Files:

  • Buffer Configuration: etc/afpd/afp_config.c - dsireadbuf parsing and validation
  • Quantum Management: libatalk/dsi/dsi_stream.c - Quantum negotiation and enforcement
  • Performance Constants: include/atalk/dsi.h - DSI_SERVQUANT_* definitions
  • Buffer Monitoring: libatalk/dsi/dsi_stream.c - Buffer fullness logging and warnings

Performance Monitoring

Buffer utilization indicators:

# Monitor DSI buffer warnings in logs
grep "readahead buffer is full" /var/log/afpd.log

# Check quantum negotiation
grep "DSI quantum" /var/log/afpd.log

# Monitor connection state changes
grep "DSI_.*:" /var/log/afpd.log

Key performance metrics:

  • Buffer overruns: Frequency of "buffer is full" warnings
  • Quantum efficiency: Data throughput vs configured quantum size
  • State transition frequency: Excessive DSI_DISCONNECTED events
  • Signal handler interference: Write interruption patterns

AFP over AppleTalk (ASP Protocol)

AppleTalk Session Protocol (ASP)

ASP provides session services over the AppleTalk protocol suite:

  • Session Management: ATP-based reliable sessions
  • Request Queuing: Multiple outstanding requests
  • Status Monitoring: Server status broadcasts
  • Error Recovery: Automatic retry mechanisms

Implementation Files:

  • ASP Implementation: libatalk/asp/asp_getsess.c - ASP session management
  • ATP Transport: libatalk/atp/atp_open.c - AppleTalk Transaction Protocol
  • Session State: libatalk/asp/asp_proto.c - ASP protocol state machine
  • Status Broadcasting: etc/afpd/status.c - Server status information via ASP
  • Header Definitions: include/atalk/asp.h - ASP protocol constants and structures

AppleTalk Protocol Stack

Application Layer:     AFP (Apple Filing Protocol)
Session Layer:         ASP (AppleTalk Session Protocol)
Transport Layer:       ATP (AppleTalk Transaction Protocol)
Network Services:      RTMP, NBP, ZIP, AEP
Network Layer:         DDP (Datagram Delivery Protocol)
Data Link Layer:       LocalTalk, EtherTalk, TokenTalk

Implementation Files:

  • ATP Layer: libatalk/atp/ - AppleTalk Transaction Protocol implementation
  • DDP Layer: etc/atalkd/ddp.c - Datagram Delivery Protocol handling
  • RTMP: etc/atalkd/rtmp.c - Routing Table Maintenance Protocol
  • NBP: etc/atalkd/nbp.c - Name Binding Protocol implementation
  • ZIP: etc/atalkd/zip.c - Zone Information Protocol
  • AppleTalk Daemon: etc/atalkd/main.c - AppleTalk routing daemon

AppleTalk Network Architecture

graph TB
    subgraph "AppleTalk Internetwork"
        subgraph "Network 1000-1000"
            A[Mac Client<br/>1000.10]
            B[Netatalk Server<br/>1000.50]
        end
        
        subgraph "Network 2000-2000"
            C[Mac Client<br/>2000.25]
            D[LaserWriter<br/>2000.100]
        end
        
        E[AppleTalk Router]
    end
    
    A -.-> B
    C -.-> E
    E -.-> B
    C -.-> D
Loading

NBP (Name Binding Protocol)

NBP provides name-to-address resolution in AppleTalk networks:

NBP Tuple Format: object:type@zone
Examples:
- MyServer:AFPServer@Engineering
- LaserWriter:LaserWriter@*
- TimeLord:TimeLord@Engineering

Implementation Files:

  • NBP Implementation: etc/atalkd/nbp.c - Name binding protocol engine
  • NBP Utilities: bin/nbp/nbplkup.c - NBP lookup utilities and tools
  • Name Registration: etc/afpd/status.c - AFP server NBP registration
  • Header Definitions: include/atalk/nbp.h - NBP protocol constants

Zone Information Protocol (ZIP)

ZIP manages AppleTalk network zones:

  • Zone Lists: Maintains network-to-zone mappings
  • Zone Information: Provides zone names for networks
  • GetZoneList: Client discovery of available zones

Implementation Files:

  • ZIP Implementation: etc/atalkd/zip.c - Zone Information Protocol engine
  • Zone Management: etc/atalkd/config.c - Zone configuration parsing
  • Network Mapping: etc/atalkd/rtmp.c - Network-to-zone relationship management
  • Header Definitions: include/atalk/zip.h - ZIP protocol constants

AFP Protocol Layer

AFP Commands

AFP defines over 100 commands organized into functional categories:

Implementation Files:

  • Command Definitions: include/atalk/afp.h - Complete AFP command constants and structures
  • Command Dispatch: etc/afpd/switch.c - AFP command routing and execution table
  • Server Commands: etc/afpd/status.c - FPGetSrvrInfo and server capability implementation
  • Session Commands: etc/afpd/auth.c - FPLogin, FPLogout, and authentication handling
  • Volume Commands: etc/afpd/volume.c - FPOpenVol, FPCloseVol, and volume management
  • Directory Commands: etc/afpd/directory.c - Directory manipulation command implementations
  • File Commands: etc/afpd/file.c - File operation command implementations
  • Fork Commands: etc/afpd/fork.c - Fork (data/resource) handling implementations

Server Commands

  • FPGetSrvrInfo: Get server capabilities and version
  • FPGetSrvrParms: Get server parameters
  • FPGetSrvrMsg: Get server message

Session Commands

  • FPLogin: Authenticate user session
  • FPLoginExt: Extended authentication
  • FPLogout: End user session
  • FPMapID: Map user/group IDs
  • FPMapName: Map user/group names

Volume Commands

  • FPOpenVol: Open volume for access
  • FPCloseVol: Close volume
  • FPGetVolParms: Get volume parameters
  • FPSetVolParms: Set volume parameters

Directory Commands

  • FPOpenDir: Open directory
  • FPCloseDir: Close directory
  • FPCreateDir: Create directory
  • FPDelete: Delete file or directory
  • FPGetFileDirParms: Get file/directory parameters
  • FPSetFileDirParms: Set file/directory parameters
  • FPEnumerate: Enumerate directory contents

File Commands

  • FPOpenFork: Open file fork
  • FPCloseFork: Close file fork
  • FPCreateFile: Create new file
  • FPRead: Read from file
  • FPWrite: Write to file
  • FPFlush: Flush file data
  • FPGetForkParms: Get fork parameters
  • FPSetForkParms: Set fork parameters

AFP Data Types

File and Directory IDs

typedef uint32_t AFPDir;     // Directory ID
typedef uint32_t AFPFile;    // File ID
typedef uint16_t AFPFork;    // Fork reference number

Volume and Server Info

struct AFPVolParms {
    uint16_t    vp_attr;        // Volume attributes
    uint16_t    vp_sig;         // Volume signature
    uint32_t    vp_cdate;       // Creation date
    uint32_t    vp_mdate;       // Modification date
    uint32_t    vp_bdate;       // Backup date
    uint16_t    vp_vid;         // Volume ID
    uint32_t    vp_bytes_free;  // Free bytes
    uint32_t    vp_bytes_total; // Total bytes
    uint8_t     vp_name[28];    // Volume name
};

Protocol Implementation Details

DSI Connection Structure

The complete DSI connection structure provides sophisticated connection management:

#define DSI_DATASIZ 65536

typedef struct DSI {
    struct DSI *next;             /* multiple listening addresses */
    AFPObj   *AFPobj;            /* back-reference to AFP object */
    
    // Server identification
    int      statuslen;
    char     status[1400];       /* server status block */
    char     *signature;         /* server signature */
    
    // Protocol header and addressing
    struct dsi_block        header;
    struct sockaddr_storage server, client;
    struct itimerval        timer;
    
    // Connection state management
    int      tickle;            /* tickle count for keepalive */
    int      in_write;          /* write operation in progress */
    int      msg_request;       /* pending message to client */
    int      down_request;      /* pending shutdown request */
    
    // Performance and flow control
    uint32_t attn_quantum;      /* attention quantum size */
    uint32_t datasize;          /* current data size */
    uint32_t server_quantum;    /* server quantum size */
    uint16_t serverID, clientID; /* connection identifiers */
    
    // I/O buffers
    uint8_t  *commands;         /* DSI receive buffer */
    uint8_t  data[DSI_DATASIZ]; /* DSI reply buffer (64KB) */
    size_t   datalen, cmdlen;   /* buffer lengths */
    off_t    read_count, write_count; /* I/O statistics */
    
    // Connection management
    uint32_t flags;             /* DSI state flags */
    int      socket;            /* AFP session socket */
    int      serversock;        /* listening socket (-1 for client connections) */
    
    // Advanced buffering system
    size_t   dsireadbuf;        /* DSI readahead buffer size */
    char     *buffer;           /* buffer start */
    char     *start;            /* current buffer head */
    char     *eof;              /* end of currently used buffer */
    char     *end;              /* buffer end */
    
#ifdef USE_ZEROCONF
    char *bonjourname;          /* Bonjour service name */
    int zeroconf_registered;    /* Zeroconf registration status */
#endif
    
    // Protocol-specific function pointers
    pid_t (*proto_open)(struct DSI *);
    void (*proto_close)(struct DSI *);
} DSI;

DSI State Management

The DSI implementation uses comprehensive state flags:

/* DSI session State flags */
#define DSI_DATA             (1 << 0) /* received a DSI command */
#define DSI_RUNNING          (1 << 1) /* received an AFP command */
#define DSI_SLEEPING         (1 << 2) /* sleeping after FPZzz */
#define DSI_EXTSLEEP         (1 << 3) /* extended sleep mode */
#define DSI_DISCONNECTED     (1 << 4) /* disconnected state after socket error */
#define DSI_DIE              (1 << 5) /* SIGUSR1, shutting down in 5 minutes */
#define DSI_NOREPLY          (1 << 6) /* generate own replies in dsi_write */
#define DSI_RECONSOCKET      (1 << 7) /* new socket from primary reconnect */
#define DSI_RECONINPROG      (1 << 8) /* reconnection in progress */
#define DSI_AFP_LOGGED_OUT   (1 << 9) /* client called afp_logout */

Advanced DSI Features

Readahead Buffering System: The DSI implementation includes sophisticated buffering for performance:

  • Configurable readahead buffer size (dsireadbuf)
  • Smart buffer management with start, eof, and end pointers
  • Efficient dsi_peek() operations for protocol parsing

Zero-Copy Operations:

#ifdef WITH_SENDFILE
extern ssize_t dsi_stream_read_file(DSI *, int, off_t off, const size_t len, const int err);
#endif

Service Discovery Integration:

  • Bonjour/Zeroconf service registration
  • UTF-8 service name support
  • Automatic service discovery for Mac clients

Connection Multiplexing:

  • Multiple listening addresses support (next pointer for address chaining)
  • Per-connection AFP object association
  • Efficient connection pooling and management

AppleTalk Address Resolution

// AppleTalk network address
struct at_addr {
    uint16_t s_net;              // Network number
    uint8_t  s_node;             // Node number
};

// NBP name tuple
struct nbptuple {
    char object[32];             // Object name
    char type[32];               // Service type  
    char zone[32];               // Zone name
};

Error Handling

Both protocol stacks implement comprehensive error handling:

AFP Error Codes

  • AFPNoErr (0): No error
  • AFPASPSessClosed (-1072): ASP session closed
  • AFPUserNotAuth (-5023): User not authenticated
  • AFPVolLocked (-5006): Volume locked
  • AFPDirNotEmpty (-5013): Directory not empty
  • AFPFileBusy (-5016): File busy
  • AFPAccessDenied (-5000): Access denied

DSI Error Recovery

  • Connection timeout: Automatic reconnection
  • Request timeout: Command retry with backoff
  • Socket errors: Connection re-establishment
  • Protocol errors: Session reset

AppleTalk Error Recovery

  • ATP timeout: Automatic retry with exponential backoff
  • Network unreachable: Route rediscovery
  • Name lookup failure: NBP retry sequence
  • Zone information stale: ZIP refresh

Performance Characteristics

TCP/IP (DSI) Performance

  • Throughput: Limited by TCP window size and network bandwidth
  • Latency: Single round-trip per AFP command
  • Concurrency: Multiple TCP connections supported
  • Optimization: TCP_NODELAY, large buffers, sendfile() usage

AppleTalk (ASP) Performance

  • Throughput: Limited by ATP packet size (578 bytes max)
  • Latency: Multiple round-trips for large operations
  • Concurrency: Limited by ATP socket availability
  • Optimization: Packet coalescing, request pipelining

This protocol documentation provides the foundation for understanding how Netatalk communicates with Mac clients across different network configurations and Mac generations.

Add a custom footer

Resources

OS Specific Guides

Technical Docs

Development

Clone this wiki locally