Dev Docs Troubleshooting

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

THESE ARE COMMUNITY DOCS

Common Issues and Troubleshooting

Overview

This guide covers frequently encountered problems with Netatalk installations, their symptoms, causes, and solutions. Issues are organized by category for easy reference.

Connection Issues

Problem: Clients Cannot Connect to Server

Implementation Files

• etc/afpd/main.c - AFP daemon initialization and network binding
• etc/netatalk/netatalk.c - Master daemon service coordination
• libatalk/dsi/dsi_tcp.c - TCP connection handling and socket management
• etc/afpd/afp_avahi.c - Bonjour/mDNS service advertisement
• etc/afpd/afp_config.c - Network interface and port configuration parsing

Symptoms

• Mac clients cannot see the server in Finder's Network section
• Connection attempts timeout or fail immediately
• "Connection failed" errors in Finder

Diagnosis

# Check if AFP daemon is running
systemctl status netatalk
ps aux | grep afpd

# Verify network listeners
netstat -tlnp | grep :548
ss -tlnp | grep :548

# Test network connectivity
telnet server_ip 548
nc -zv server_ip 548

# Check firewall rules
iptables -L | grep 548
ufw status | grep 548

Common Causes and Solutions

1. AFP Daemon Not Running

# Start the service
systemctl start netatalk
systemctl enable netatalk

# Check for startup errors
journalctl -u netatalk -f

2. Firewall Blocking Connections

# Ubuntu/Debian with ufw
ufw allow 548

# RHEL/CentOS with firewalld
firewall-cmd --permanent --add-port=548/tcp
firewall-cmd --reload

# iptables rule
iptables -A INPUT -p tcp --dport 548 -j ACCEPT

3. Network Interface Binding Issues

# /etc/netatalk/afp.conf
[Global]
afp listen = 0.0.0.0:548     # Listen on all interfaces
# OR
afp listen = 192.168.1.100:548  # Specific interface
afp interfaces = eth0        # Limit to specific interface

4. Service Discovery Problems

# Enable Bonjour/mDNS
[Global]
zeroconf = yes

# Check Avahi daemon
systemctl status avahi-daemon

Problem: Connection Drops Frequently

Implementation Files

• libatalk/dsi/dsi_stream.c - DSI connection state management and timeouts
• etc/afpd/afp_options.c - Connection timeout and keepalive configuration
• libatalk/dsi/dsi_tcp.c - TCP socket keepalive and buffer settings
• etc/afpd/switch.c - AFP session management and idle handling

Symptoms

• Clients disconnect after period of inactivity
• "Server unexpectedly closed connection" errors
• File transfers interrupted

Solutions

# /etc/netatalk/afp.conf
[Global]
# Increase connection timeout
sleep time = 60

# TCP keepalive settings
tcp rcvbuf = 131072
tcp sndbuf = 131072

# Client idle timeout
disconnect time = 300

Authentication Issues

Problem: Login Failures

Implementation Files

• etc/uams/ - User Authentication Module implementations directory
• etc/afpd/auth.c - Core authentication processing and UAM coordination
• etc/uams/uams_pam.so.c - PAM authentication module implementation
• etc/uams/uams_dhx2.so.c - DHX2 encrypted authentication module
• etc/uams/uams_guest.so.c - Guest authentication module
• libatalk/util/server_child.c - Authentication state management

Symptoms

• "Authentication failed" errors
• Valid credentials rejected
• Guest access not working

Diagnosis

# Check available UAMs
afpd -V | grep UAM

# Test user account
id username
getent passwd username

# Check AFP password file
cat /etc/netatalk/afppasswd

# Debug authentication
tail -f /var/log/netatalk.log

Common Solutions

1. Missing or Incorrect UAM Modules

[Global]
uam list = uams_dhx2.so uams_dhx.so uams_pam.so uams_guest.so
uam path = /usr/local/lib/netatalk

2. PAM Configuration Issues

# Create /etc/pam.d/netatalk
cat > /etc/pam.d/netatalk << EOF
#%PAM-1.0
auth        required    pam_unix.so
account     required    pam_unix.so
EOF

3. AFP Password File Problems

# Recreate AFP password file
afppasswd -c username

# Set correct permissions
chown root:root /etc/netatalk/afppasswd
chmod 600 /etc/netatalk/afppasswd

4. Guest Access Issues

[Global]
guest account = nobody

[Volume]
guest ok = yes

Problem: Permission Denied Errors

Implementation Files

• etc/afpd/unix.c - Unix permission checking and file access control
• etc/afpd/volume.c - Volume-level permission enforcement
• libatalk/vfs/ - Virtual File System permission handling directory
• etc/afpd/file.c - File operation permission validation
• etc/afpd/directory.c - Directory permission checking and ACL support

Symptoms

• Cannot read/write files despite correct credentials
• "You don't have permission" errors
• Volume appears but files are inaccessible

Diagnosis

# Check file system permissions
ls -la /path/to/volume/
getfacl /path/to/volume/

# Check user/group membership
groups username
id username

# Test direct file access
sudo -u username ls /path/to/volume/

Solutions

# Fix permission model
[Volume]
unix priv = yes
inherit perms = yes

# Set appropriate permissions
file perm = 0644
directory perm = 0755
umask = 022

# Force user/group
force user = shareuser
force group = sharegroup

Volume Issues

Problem: Volumes Not Appearing

Implementation Files

• etc/afpd/volume.c - Volume initialization and configuration processing
• etc/afpd/afp_options.c - Volume configuration parsing from afp.conf
• etc/afpd/enumerate.c - Volume enumeration for client display
• libatalk/vfs/ - Volume filesystem interface implementations
• etc/afpd/main.c - Volume loading during AFP daemon startup

Symptoms

• Configured volumes don't show up in Finder
• Server connects but no volumes available
• Some volumes missing from list

Diagnosis

# Check configuration syntax
netatalk -t  # (Not implmented yet)

# Verify volume paths exist
ls -la /path/to/volume/

# Check volume permissions
stat /path/to/volume/

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

Solutions

# Create missing directories
mkdir -p /path/to/volume
chown appropriate_user:appropriate_group /path/to/volume

# Fix configuration syntax
nano /etc/netatalk/afp.conf

# Restart service
systemctl restart netatalk

Problem: Time Machine Backup Failures

Implementation Files

• etc/afpd/volume.c - Time Machine volume configuration and validation
• etc/afpd/afp_options.c - Time Machine specific option parsing
• etc/afpd/file.c - File operations for sparsebundle handling
• libatalk/adouble/ - AppleDouble metadata handling for Time Machine
• etc/afpd/desktop.c - Desktop database management for backup metadata

Symptoms

• "Time Machine couldn't complete the backup"
• Backup starts but fails partway through
• Sparsebundle corruption errors

Diagnosis

# Check Time Machine volume settings
grep -A 10 "time machine" /etc/netatalk/afp.conf

# Monitor disk space
df -h /srv/timemachine/

# Check for filesystem errors
fsck /dev/disk_device

Solutions

[TimeMachine]
path = /srv/timemachine
time machine = yes
vol size limit = 1000000    # Set appropriate limit
tm used size = yes
spotlight = no
ea = ad

# Fix sparsebundle corruption
hdiutil attach /path/to/backup.sparsebundle
diskutil repairVolume /Volumes/BackupVolume
hdiutil detach /Volumes/BackupVolume

Performance Issues

Problem: Slow File Transfers

Implementation Files

• libatalk/dsi/dsi_stream.c - DSI data streaming and buffer management
• libatalk/dsi/dsi_tcp.c - TCP buffer optimization and socket tuning
• etc/afpd/fork.c - File fork handling and data transfer optimization
• etc/afpd/afp_options.c - Performance-related configuration parsing
• libatalk/util/queue.c - I/O queue management for throughput optimization

Symptoms

• File transfers much slower than expected
• Network appears underutilized during transfers
• Large files take excessive time

Diagnosis

# Monitor network utilization
iftop -i eth0
netstat -i

# Check system resources
top
iostat 1

# Test network speed
iperf3 -s  # On server
iperf3 -c server_ip  # On client

Solutions

[Global]
# Optimize TCP buffers
tcp rcvbuf = 262144
tcp sndbuf = 262144
dsireadbuf = 64

# Connection tuning
max connections = 50
sleep time = 1

# Enable sendfile if available
echo 'net.core.rmem_max = 262144' >> /etc/sysctl.conf
echo 'net.core.wmem_max = 262144' >> /etc/sysctl.conf
sysctl -p

Problem: High Memory Usage

Implementation Files

• libatalk/util/server_child.c - Child process memory management
• etc/afpd/directory.c - Directory cache memory allocation and cleanup
• libatalk/cnid/cnid_dbd.c - CNID database connection pooling and memory
• libatalk/dsi/dsi_stream.c - DSI buffer memory management
• libatalk/util/talloc.c - Memory allocation tracking and leak detection

Symptoms

• Netatalk processes consuming excessive memory
• System becomes unresponsive
• Out of memory errors

Diagnosis

# Monitor memory usage
ps aux | grep afpd | head -20
pmap -d $(pgrep afpd)

# Check for memory leaks
valgrind --leak-check=full afpd -d

Solutions

[Global]
# Limit connections
max connections = 100

# Reduce cache sizes
cache size = 32768

[Volume]
# Disable unnecessary features
spotlight = no
stat vol = no

Database Issues

Problem: CNID Database Corruption

Implementation Files

• etc/cnid_dbd/ - CNID database daemon implementation directory
• libatalk/cnid/cnid_dbd.c - CNID database client interface
• etc/cnid_metad/ - CNID metadata coordinator daemon
• libatalk/cnid/ - CNID backend implementations directory
• include/atalk/cnid_dbd_private.h - CNID database internal structures

Symptoms

• Files appear with wrong icons or types
• "Database needs repair" messages in logs
• File operations extremely slow

Diagnosis

# Check database files
ls -la /var/lib/netatalk/CNID/

# Verify database integrity
db_verify /var/lib/netatalk/CNID/cnid2.db

# Check database logs
tail -f /var/log/netatalk.log | grep -i cnid

Solutions

# Stop netatalk service
systemctl stop netatalk

# Backup database
cp -r /var/lib/netatalk/CNID /var/lib/netatalk/CNID.backup

# Rebuild database
rm -rf /var/lib/netatalk/CNID/*
systemctl start netatalk

# OR manual database repair
db_recover -h /var/lib/netatalk/CNID

Problem: Database Lock Issues

Implementation Files

• etc/cnid_dbd/main.c - CNID database daemon startup and lock management
• etc/cnid_dbd/dbd_lookup.c - Database lookup operations with locking
• libatalk/cnid/cnid_dbd.c - Client-side database locking coordination
• etc/cnid_metad/cnid_metad.c - Cross-volume database lock coordination

Symptoms

• "Database locked" errors
• CNID operations hang
• Multiple database processes

Solutions

# Stop all netatalk processes
systemctl stop netatalk
pkill -f cnid

# Remove lock files
rm -f /var/lib/netatalk/CNID/__db.*

# Restart service
systemctl start netatalk

Spotlight Issues

Problem: Search Not Working

Implementation Files

• etc/afpd/spotlight.c - Spotlight search query processing
• etc/afpd/spotlight_marshall.c - Spotlight protocol marshalling
• libatalk/util/tracker.c - Tracker search engine integration
• etc/afpd/volume.c - Spotlight volume configuration and indexing control
• include/atalk/spotlight.h - Spotlight protocol definitions and structures

Symptoms

• Spotlight searches return no results
• Search functionality unavailable
• Indexing appears stalled

Diagnosis

# Check Tracker status
tracker3 status

# Verify Spotlight configuration
grep -i spotlight /etc/netatalk/afp.conf

# Check indexing process
ps aux | grep tracker

Solutions

# Restart Tracker
tracker3 reset --hard
systemctl restart tracker-miner-fs

# Reindex volume
tracker3 index --file /path/to/volume

[Volume]
# Enable Spotlight properly
spotlight = yes
spotlight size limit = 10000

Service Discovery Issues

Problem: Server Not Appearing in Network Browser

Implementation Files

• etc/afpd/afp_avahi.c - Avahi/Bonjour service registration and advertisement
• etc/netatalk/netatalk.c - Master daemon service discovery coordination
• libatalk/util/avahi.c - Avahi integration utilities
• etc/afpd/main.c - Service discovery initialization during startup

Symptoms

• Server doesn't appear in Finder sidebar
• Bonjour/mDNS advertisement not working
• Manual connection required

Diagnosis

# Check Avahi status
systemctl status avahi-daemon

# Verify service advertisement
avahi-browse -at

# Test mDNS resolution
dig @224.0.0.251 -p 5353 _afpovertcp._tcp.local

Solutions

# Enable and start Avahi
systemctl enable avahi-daemon
systemctl start avahi-daemon

# Check Avahi configuration
cat /etc/avahi/avahi-daemon.conf

[Global]
zeroconf = yes
mimic model = Xserve

Log Analysis

Enabling Debug Logging

Implementation Files

• libatalk/util/logger.c - Core logging system with level control
• include/atalk/logger.h - Log level definitions and logging macros
• etc/afpd/main.c - AFP daemon logging initialization
• etc/netatalk/netatalk.c - Master daemon logging configuration
• include/atalk/debug.h - Debug-specific logging macros and conditionals

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

# Log to separate file
log file = /var/log/netatalk-debug.log

Common Log Messages

Authentication Failures:

afpd[pid]: login authentication failed for user
afpd[pid]: UAM: uams_dhx2.so: login authentication failed

Permission Errors:

afpd[pid]: AFP_ACCESS denied: path/to/file
afpd[pid]: perm_check: Permission denied

Database Issues:

cnid_dbd[pid]: Error opening database
cnid_dbd[pid]: Berkeley DB error: Lock table is full

Log File Locations

Implementation Files

• libatalk/util/logger.c - Log file path configuration and rotation

• etc/afpd/afp_options.c - Log file option parsing from configuration

• include/atalk/paths.h - Default log file path definitions

• Main log: /var/log/netatalk.log or syslog

• Debug log: Custom location via log file setting

• System journal: journalctl -u netatalk

• Daemon-specific: /var/log/daemon.log

Emergency Recovery

Complete Service Reset

Implementation Files

• etc/netatalk/netatalk.c - Master daemon shutdown and cleanup procedures
• etc/afpd/main.c - AFP daemon graceful shutdown implementation
• etc/cnid_dbd/main.c - CNID database daemon shutdown and recovery
• libatalk/util/server_child.c - Child process cleanup and termination
• libatalk/cnid/cnid_dbd.c - Database connection cleanup and reset

# Stop all services
systemctl stop netatalk
pkill -f afpd
pkill -f cnid

# Backup configuration
cp -r /etc/netatalk /etc/netatalk.backup

# Reset to minimal configuration
cat > /etc/netatalk/afp.conf << EOF
[Global]
log level = default:info
uam list = uams_dhx2.so uams_guest.so

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

# Create test directory
mkdir -p /tmp/netatalk-test
chmod 777 /tmp/netatalk-test

# Restart service
systemctl start netatalk

Database Recovery

# Complete database reset
systemctl stop netatalk
rm -rf /var/lib/netatalk/CNID/*
systemctl start netatalk

# This will rebuild all CNID databases from scratch
# Note: This may change file IDs, affecting aliases and bookmarks

This troubleshooting guide covers the most common issues encountered with Netatalk installations. For issues not covered here, consult the project documentation, community forums, or consider filing a bug report with detailed logs and system information.