netatalk.io

Dev Docs Netatalk Configuration

Netatalk Configuration Guide

Overview

This guide covers the configuration of Netatalk services, including AFP volumes, authentication methods, network settings, and advanced features. Netatalk uses a centralized configuration system based on INI-style configuration files.

Implementation Files:

• libatalk/iniparser/ - INI-style configuration file parsing library
• etc/afpd/afp_config.c - AFP daemon configuration processing and validation
• libatalk/util/netatalk_conf.c - Main configuration management and global settings
• include/atalk/netatalk_conf.h - Configuration structure definitions and constants
• etc/netatalk/netatalk.c - Master daemon configuration coordination

Configuration Files

Primary Configuration File

Example Location: /etc/netatalk/afp.conf

The main configuration file uses INI format with sections for global settings, individual volumes, and service-specific options.

Implementation Files:

• libatalk/iniparser/iniparser.c - INI file parsing and section/key extraction
• libatalk/util/netatalk_conf.c - Configuration file loading and structure population
• etc/afpd/afp_config.c - AFP-specific configuration validation and processing

# /etc/netatalk/afp.conf
[Global]
# Global AFP settings
hostname = "My Netatalk Server"
log level = default:info
uam list = uams_dhx2.so uams_dhx.so uams_pam.so

[Homes]
# User home directories
basedir regex = /home

[TimeMachine]
# Time Machine volume
path = /srv/timemachine
time machine = yes
vol size limit = 1000000

Additional Configuration Files

• /etc/netatalk/afppasswd: Local AFP user database
• /etc/netatalk/atalkd.conf: AppleTalk daemon configuration
• /etc/netatalk/papd.conf: Printer daemon configuration
• /var/lib/netatalk/: Runtime state and database files

Global Configuration

Implementation Files:

• libatalk/util/netatalk_conf.c - Global configuration processing and defaults
• etc/afpd/afp_config.c - Server identification and network configuration
• libatalk/util/server_logging.c - Logging configuration and initialization

Basic Server Settings

[Global]
# Server identification
hostname = "Netatalk Server"
server name = "AFP Server"

# Network configuration
afp listen = 192.168.1.100:548
afp interfaces = eth0

# Logging configuration
log level = default:info
log file = /var/log/netatalk.log

# Performance settings
max connections = 200
sleep time = 10
tcp rcvbuf = 87380
tcp sndbuf = 87380

Authentication Configuration

Implementation Files:

• etc/afpd/auth.c - Authentication configuration processing and UAM loading
• etc/uams/ - User Authentication Module implementations (DHX, DHX2, PAM, Guest, Kerberos)
• libatalk/util/netatalk_conf.c - Authentication method selection and configuration

[Global]
# Authentication modules (UAMs)
uam list = uams_dhx2.so uams_dhx.so uams_pam.so uams_guest.so
uam path = /usr/local/lib/netatalk

# Guest access
guest account = nobody
save password = yes

# Security settings
admin group = @admin
passwd file = /etc/netatalk/afppasswd
passwd minlen = 6

# Login messages
login message = "Welcome to Netatalk Server"

Service Discovery

Implementation Files:

• etc/afpd/afp_zeroconf.c - Bonjour/mDNS service advertisement
• etc/atalkd/main.c - AppleTalk zone configuration and registration
• libatalk/util/server_ipc.c - Service coordination and discovery management

[Global]
# Bonjour/Zeroconf settings
zeroconf = yes
mimic model = Xserve

# Legacy AppleTalk settings (if supported)
appletalk = yes
zone = "Engineering"

Volume Configuration

Implementation Files:

• libatalk/util/netatalk_conf.c - Volume configuration parsing and validation
• etc/afpd/volume.c - Volume mounting, permissions, and access control
• libatalk/util/volinfo.c - Volume information and metadata management
• etc/afpd/afp_avahi.c - Volume service advertisement via Avahi/Bonjour

Basic Volume Definition

[MyVolume]
# Basic volume settings
path = /srv/shared
valid users = @users
read only = no

# Access permissions
file perm = 0644
directory perm = 0755
umask = 022

# Volume options
case sensitive = no

Volume Types and Templates

Implementation Files:

• etc/afpd/volume.c - Volume type handling and template processing
• libatalk/util/netatalk_conf.c - Home directory and template volume configuration
• etc/afpd/afp_config.c - Volume type validation and setup

User Home Directories

[Homes]
# Automatically create volumes for user home directories
basedir regex = /home
home name = "Home Directory"
valid users = @users

# Home directory specific settings
inherit perms = yes
unix priv = yes

Time Machine Volume

[TimeMachine]
path = /srv/timemachine
time machine = yes

# Size limits
vol size limit = 1000000  # 1TB in MB
quota = yes

# Time Machine specific options
tm used size = yes
spotlight = no

Public Share

[Public]
path = /srv/public
guest ok = yes
read only = no

# Public access settings
unix priv = no
file perm = 0666
directory perm = 0777

Read-Only Archive

[Archive]
path = /srv/archive
read only = yes
guest ok = yes

# Archive optimization
spotlight = yes
vol charset = UTF8

Advanced Volume Options

Security and Access Control

[Secure]
path = /srv/secure

# Access control
valid users = @secure-users
invalid users = guest nobody
admin users = @admin

# Unix permissions
unix priv = yes
inherit perms = yes
force user = secure-user
force group = secure-group

Spotlight Integration

[SearchableVolume]
path = /srv/documents
spotlight = yes

# Spotlight specific settings
spotlight expr = "kMDItemContentType != 'public.folder'"
spotlight size limit = 10000  # 10GB limit for indexing

Authentication Methods

Implementation Files:

• etc/afpd/auth.c - Authentication method coordination and UAM selection
• etc/uams/uams_pam.so.c - PAM authentication module implementation
• include/atalk/uam.h - User Authentication Module interface definitions

PAM Authentication

[Global]
uam list = uams_pam.so

# PAM service configuration
# Requires /etc/pam.d/netatalk or system-wide PAM setup

Create /etc/pam.d/netatalk:

#%PAM-1.0
auth        required    pam_unix.so
account     required    pam_unix.so

Local Password File

Implementation Files:

• etc/uams/randnum.c - Random Number authentication with local password file
• bin/afppasswd/afppasswd.c - AFP password file management utility

[Global]
uam list = uams_randnum.so
passwd file = /etc/netatalk/afppasswd

Create local users with afppasswd:

# Add user to AFP password file
afppasswd -a username

# Change user password
afppasswd -c username

# Delete user
afppasswd -d username

LDAP Authentication

Implementation Files:

• etc/uams/uams_pam.so.c - PAM-based LDAP authentication integration
• etc/afpd/auth.c - LDAP authentication configuration processing
• System PAM configuration files for LDAP integration

[Global]
uam list = uams_pam.so

# Configure PAM to use LDAP
# Requires pam_ldap configuration

Example PAM LDAP configuration in /etc/pam.d/netatalk:

#%PAM-1.0
auth        sufficient  pam_ldap.so
auth        required    pam_unix.so     try_first_pass
account     sufficient  pam_ldap.so
account     required    pam_unix.so

Kerberos/GSSAPI

Implementation Files:

• etc/uams/uams_gss.so.c - GSSAPI/Kerberos authentication module
• etc/afpd/gettok.c - Kerberos token processing and validation
• libatalk/util/gss_util.c - GSSAPI utility functions and ticket management

[Global]
uam list = uams_gss.so

# Kerberos configuration
# Requires proper krb5.conf setup and service principals

Network Configuration

Implementation Files:

• etc/afpd/afp_config.c - Network interface and TCP configuration
• libatalk/dsi/dsi_tcp.c - DSI over TCP socket management and tuning
• etc/netatalk/netatalk.c - Network service initialization and binding

TCP/IP Settings

[Global]
# Bind to specific interfaces
afp listen = 192.168.1.100:548 [::1]:548

# Interface restrictions
afp interfaces = eth0 eth1

# TCP tuning
tcp rcvbuf = 131072    # 128KB receive buffer
tcp sndbuf = 131072    # 128KB send buffer

AppleTalk Configuration

Implementation Files:

• etc/atalkd/config.c - AppleTalk network configuration parsing
• etc/atalkd/main.c - AppleTalk daemon initialization and zone setup
• libatalk/compat/ - AppleTalk compatibility layer for modern systems

[Global]
# Enable AppleTalk (if kernel support available)
appletalk = yes

# AppleTalk zone
zone = "Engineering Zone"

# Network configuration file (optional)
# Detailed AppleTalk settings in separate file

Service Discovery

Implementation Files:

• etc/afpd/afp_zeroconf.c - Zeroconf/Bonjour service discovery implementation
• etc/afpd/afp_avahi.c - Avahi mDNS service registration and management
• libatalk/util/netatalk_conf.c - Service discovery configuration processing

[Global]
# Bonjour/mDNS service discovery
zeroconf = yes

# Server model advertisement
mimic model = Xserve

# Additional service advertisements
advertise ssh = yes

Logging Configuration

Implementation Files:

• libatalk/util/server_logging.c - Logging system initialization and level management
• include/atalk/logger.h - Logging interface definitions and macros
• etc/afpd/main.c - AFP daemon logging setup and configuration

Log Levels

[Global]
# Global log level
log level = default:info

# Per-component log levels
log level = default:info afpd:debug cnid:warning

# Detailed debugging
log level = default:debug9

Log Destinations

Implementation Files:

• libatalk/util/logger.c - Log destination configuration (file, syslog)
• etc/netatalk/netatalk.c - Master daemon logging coordination
• System syslog configuration for Netatalk log routing

[Global]
# Log to file
log file = /var/log/netatalk/afpd.log

# Log to syslog (default)
# log file = syslog

# Disable logging
# log file = /dev/null

Syslog Configuration

Add to /etc/rsyslog.conf or /etc/syslog.conf:

# Netatalk logging
daemon.info                     /var/log/netatalk.log
daemon.debug                    /var/log/netatalk-debug.log

Advanced Features

Implementation Files:

• etc/afpd/spotlight.c - Spotlight search integration and configuration
• etc/afpd/volume.c - Volume-specific advanced feature configuration
• libatalk/util/netatalk_conf.c - Advanced feature parsing and validation

Spotlight Search Configuration

[Global]
# Global Spotlight settings
spotlight = yes

[MyVolume]
path = /srv/documents
spotlight = yes

# Spotlight tuning
spotlight expr = "kMDItemFSName != '.*'"  # Exclude hidden files
spotlight size limit = 5000               # 5GB indexing limit

Configure GNOME Tracker (if using):

# ~/.config/tracker/tracker.cfg
[indexing]
enable-monitors=false
crawling-interval=7200

File Type Mapping

Implementation Files:

• etc/afpd/filedir.c - File type mapping and Mac metadata handling
• libatalk/adouble/ad_attr.c - AppleDouble attribute and type mapping
• etc/afpd/volume.c - Volume-specific file type configuration

[Global]
# Custom file type mappings
# map file extension to Mac file type/creator
vol dbpath = /var/lib/netatalk/CNID

[MyVolume]
# Volume-specific type mapping
veto files = *.tmp/~*/.*

CNID Backend Configuration

Implementation Files:

• libatalk/util/netatalk_conf.c - CNID backend selection and configuration
• etc/cnid_dbd/main.c - Berkeley DB CNID daemon configuration
• libatalk/cnid/ - CNID backend interface and implementation files

[Global]
# CNID backend selection
cnid scheme = dbd

[MyVolume]
# Volume-specific CNID settings
cnid scheme = dbd
vol dbpath = /var/lib/netatalk/volumes/MyVolume

Performance Tuning

Implementation Files:

• etc/afpd/afp_config.c - Performance parameter configuration and validation
• libatalk/dsi/dsi_tcp.c - TCP buffer and connection tuning
• etc/netatalk/netatalk.c - Process limit and resource management

Connection and Process Limits

[Global]
# Connection limits
max connections = 200
sleep time = 10

Filesystem Optimization

Implementation Files:

• etc/afpd/volume.c - Volume-specific performance and caching configuration
• etc/afpd/directory.c - Directory caching and optimization settings
• libatalk/util/netatalk_conf.c - Filesystem performance parameter processing

[HighPerformanceVolume]
path = /srv/fast-storage

# Performance settings
stat vol = no         # Don't update volume statistics
ea = ad               # Use AppleDouble for extended attributes
vol charset = UTF8    # Efficient character encoding
mac charset = MAC_ROMAN

# Caching
dircachesize = 131072 # Max directory cache entries
dsireadbuf = 32       # Scale factor for DSI/TCP readahead buffer, default is 12. Is multiplies of DSI server quantum (1MB by default).

stat vol = no         # Don't update volume stats frequently

Database Tuning

Implementation Files:

• etc/cnid_dbd/main.c - Berkeley DB daemon configuration and optimization
• etc/cnid_metad/main.c - CNID metadata coordinator configuration
• libatalk/cnid/cnid_dbd/ - Berkeley DB backend tuning and configuration

[Global]
# Berkeley DB tuning
cnid server ipconfig = localhost:4700

# CNID database optimization occurs in Berkeley DB configuration
# Set via environment variables or database-specific config

Security Configuration

Implementation Files:

• etc/afpd/volume.c - Volume access control and permission management
• etc/afpd/auth.c - Authentication and authorization configuration
• libatalk/util/netatalk_conf.c - Security parameter validation and processing

Access Control

[Global]
# Global security settings
admin group = @admin
guest account = nobody

[SecureVolume]
path = /srv/confidential

# Strict access control
valid users = @management @hr
invalid users = @interns @contractors
admin users = @it-admin

# Force ownership
force user = secure-data
force group = secure-data

Network Security

Implementation Files:

• etc/afpd/afp_config.c - Network interface restrictions and security settings
• libatalk/dsi/dsi_tcp.c - TCP connection security and validation
• etc/afpd/auth.c - Authentication security requirements and enforcement

[Global]
# IP-based restrictions (if supported by platform)
afp interfaces = eth0  # Limit to internal network interface

# Authentication requirements
uam list = uams_dhx2.so  # Require encrypted authentication
guest account =          # Disable guest access

File System Security

Implementation Files:

• etc/afpd/volume.c - Unix privilege enforcement and permission management
• etc/afpd/file.c - File operation security and access validation
• libatalk/adouble/ad_lock.c - File locking and concurrent access security

[SecureVolume]
# Unix privilege enforcement
unix priv = yes
inherit perms = yes

# Strict permissions
file perm = 0640
directory perm = 0750
umask = 027

# Prevent certain operations
delete readonly = no

Troubleshooting Configuration

Debug Logging

[Global]
# Maximum debug logging
log level = default:debug9 afpd:debug9 cnid:debug9

# Separate debug log
log file = /var/log/netatalk-debug.log

Connection Debugging

[Global]
# Connection debugging
sleep time = 1         # Reduce sleep time for testing
max connections = 10   # Limit connections during debugging

# Network debugging
tcp rcvbuf = 8192     # Smaller buffers for testing
tcp sndbuf = 8192

Volume Testing

[TestVolume]
path = /tmp/netatalk-test
guest ok = yes

# Minimal restrictions for testing
read only = no
unix priv = no
file perm = 0666
directory perm = 0777

Configuration Validation

Syntax Checking

# Test specific volume
afpd -d -f /etc/netatalk/afp.conf

Runtime Configuration

# Display active configuration
afpd -V

# Monitor configuration changes
tail -f /var/log/netatalk.log

This configuration guide provides comprehensive coverage of Netatalk setup options, from basic file sharing to advanced enterprise deployments with sophisticated authentication and access control requirements.

Footnotes

This is a mirror of the Netatalk GitHub Wiki

Last updated 2025-12-27