Setting up Apple Filing Protocol and Bonjour under Debian

Got a Mac ? Got a Linux box that you use as a file server on your home network? Sick of problems with samba? So was I, until today when I decided to figure out how to setup Apple Filing Protocol (AFP) and Bonjour under Linux, debian in my case. In the following tutorial, we’re going to install and configure, Netatalk and Avahi. I’m also going to show you how to create a TimeMachine backup location on your file server, and get your Mac to recognize / use it.

Building Netatalk

Netatalk is the Open Source implementation of AFP. Since Mac OS X requires encryption to work properly, and the standard netatalk package doesn’t include this feature. So we are going to build our own netatalk package from source with encryption enabled. To start, we’re going to download install dependencies for netatalk. Then ensure we install the dependencies for encryption support, and finally grab the source for netatalk.

sudo apt-get build-dep netatalk
sudo apt-get install cracklib2-dev fakeroot libssl-dev
sudo apt-get source netatalk

Now that we have source we can move into the netatalk directory. The first thing we need to do is change the version number on the package, then we can build the package with encryption enabled.

Your version numbers may differ, but please increment, and use +SSL in order to differentiate your custom package from the standard Debian one…the head command will output the current package version for you. In my case, it showed netatalk (2.0.3-11+lenny1)

cd netatalk-2.0.3
head -n 1 debian/changelog
dch -v 2.0.3-12+SSL

This will take us into an editor to add notes, feel free to add a comment stating that this is a custom package compiled to add SSL support. To exit the editor, press <ctrl>+x then y <enter> to save.

Now that our version information has been saved into the package. We can start our compile.

sudo DEB_BUILD_OPTIONS=ssl dpkg-buildpackage -rfakeroot

This could take a couple minutes… Go grab a bee^Hverage.

Once completed, hopefully without errors (the ones about being unable to sign the package are ok) you should have a netatalk-2..something.deb package in your home directory. Now, we need to install it, and place a hold on it to prevent apt from replacing it with a version from the Debian repository. To do so, enter the following commands.

sudo dpkg -i ~/netatalk_2*.deb
aptitutde hold netatalk

Configure Netatalk

The first thing we are going to do, is disable some services provided by netatalk which are not need for just file sharing. This will speed up the startup and response time of netatalk significantly. In the following examples I’ll be using Vi, but feel free to fire up your favorite text editor.

sudo vi /etc/default/netatalk

Locate the following startup options and change them as noted below. If you’re also interested in sharing a Linux connected printer, enable the pap daemon aswell.


The cnid_meta daemon service handles all the metadata for us which would get lost since your Linux box isn’t formatted as Apple’s HFS+. Go ahead and save an exit this file, and lets move on to the afpd.conf file.

sudo vi /etc/netatalk/afpd.conf

At the very bottom of the file you should see a line similar to the following line. Replace it with the following, save and exit.

– -transall -uamlist, -nosavepassword -advertise_ssh

Configuring shared volumes

The next step is telling afpd what volumes we want to share. This is configured in the /etc/netatalk/AppleVolumes.default file.

Scroll to the bottom of the document and define your shared volumes. There should already be a line starting with ~/ allowing the sharing of home directories via AFP.

~/ "$u" cnidscheme:cdb

You can setup as many shared volumes as you wish. You can even define which users are allowed to access each share. You do this using the allow option. On my server, I have the following setup for my mp3 collection.

/server/mp3 mp3 allow:tonhe,jessi

Since you’ll probably want to use your file server as a time machine backup, we can also define a volume just for that. Create a directory, and set it up using the following line.

/home/USERNAME/TimeMachine TimeMachine allow:USERNAME cnidscheme:cdb options:usedots,upriv

The usedots option is required if you want to use hidden files and folders starting with a period. Without usedots, afpd would encode them as :2e which is incorrect. If you’re on Leopard and have no Tiger installed Macs in your network or mixed OS X versions in your network you should use the upriv option which adds support for AFP3 unix privileges. If you have Macs with Tiger installed just use options:usedots to avoid unexpected behavior. Finally if you want more stability and can accept slower file transfers you can use the dbd cnidscheme (cnidscheme:dbd).

Once you’re done setting up your shared volumes, restart netatalk using the init.d script.

sudo /etc/init.d/netatalk restart

Even so we have a fully configured AFP it will not show up in the Finder sidebar on OS X, it is however reachable via ‘Go -> Connect to Server’ in Finder). OS X use a service called Bonjour for automagic discovery, which displays the server on your sidebar. Linux can emulate this functionality with an open source implementation of Bonjour called Avahi.

Installing Avahi

Avahi is the daemon that will advertise all defined services across your network just like Bonjour does. We are going to install the avahi daemon and the mDNS library used for imitating the Bonjour service. When fully configured this will allow machines running OS X in your network to discover your Linux box automatically.

sudo apt-get install avahi-daemon
sudo apt-get install libnss-mdns

Our configuration starts with the /etc/nsswitch.conf file. Simply add “mdns” to the end of the line that starts with “hosts:” – when completed it should look something like this.

hosts: files mdns4_minimal [NOTFOUND=return] dns mdns4 mdns

Now we have to tell Avahi which services it should advertise across the network, in our case we just want to advertise AFP volumes. This is done by creating a XML file for each service in the /etc/avahi/services/ directory. Create the file /etc/avahi/services/afpd.service and insert the following XML code.





0 model=Xserve

The only thing left to do is restart Avahi.

sudo /etc/init.d/avahi-daemon restart

Thats it, you have configured the Avahi daemon to advertise AFP sharing across your network which should cause any computer running OS X to automagically discover it. Within a few moments it should show up in your Finder’s sidebar. You should be able to connect using the username and password from your Linux box. Once connected you should see the Volumes we defined in the AppleVolumes.default file.

Configure Time Machine

Your Mac needs to be configured to allow Unsupported Network shares to be used for time machine. This option is only configurable (like many things) from the terminal.

defaults write TMShowUnsupportedNetworkVolumes 1

Now, just simply mount the TimeMachine volume, and choose it as the backup disk in the Time Machine system preferences. Time Machine will create a sparsebundle disk image inside the volume and mounts that too, since your drive is not formated using the Mac native format HFS+. Because Time Machine backups everything to the disk image all metadata, like creation dates and such, will be preserved.

When your first Time Machine backup is done you can remove all Volumes and the next time Time Machine starts it will automagically mount the disk image from your TimeMachine volume on your Linux box without mounting the whole TimeMachine volume.

Thats it

As you can see, its pretty simple to setup AFP under Linux and relieve yourself of all your samba woes. Obviously I could of used NFS instead of AFP, but from what I’ve been told, nothing beats AFP speed and reliability. As usual, if you have any problems, or questions feel free to comment below.

Network engineer currently servicing the enterprise data center market. I started working on networks in the ’90s and still feel like that was just a few years ago. Jack of all trades, master of none; I love to learn about everything. Feel free to ask me about photography, woodworking, nhra, watches, or 3x Gold ETFs — For feedback, please leave a comment on the article in question, and I’ll gladly moderate it several weeks later. For everything else including fan mail or death threats, contact him via twitter.
  • Michael


    I just encountered that my Mac with Snow Leopard can't connect to my debian box with netatalk 2.0.3 anymore. Any ideas?


    • Tony

      I'd take a look in syslog and see what kind of errors you may be seeing…

  • heretique

    I followed all the steps carefully, including compilation of netatalk from sources (and believe me, I hate compiling from source :)) and it is working on Snow Leopard!
    My linux box is debian 2.6.18-5-686.

  • Thomas Carlson

    I used your tutorial and it worked fine except that my Debian Linux server has to be accessed through Connect to Server in the top bar as the icon that appears in the finder's sidebar is non-functional. What would cause that?

    • Tony

      I imagine something is not configured properly with Avahi.. I just verified that this is working fine on Debian 5.0 after upgrading myself…

      If you can't find any misconfiguration, check syslog, see what errors you see locally, and on your mac when connecting..

  • J Krische

    For those having difficulty with newer versions of netatalk (>=2.0.4, IIRC), particularly our ubuntu cousins, try the following change to afpd.conf:

    – -transall -uamlist, -nosavepassword -advertise_ssh

    (changed to

    just change that line by one character, restart netatalk and see if that helps.

  • Steve

    I've been having problems with my Samba shares on a Debian Lenny server hanging on me, and have switched to AFP using these instructions. They are much appreciated!

    I'm seeing one small, weird issue, though: now when I run a standard update/upgrade to pick up security updates, aptitude always wants to "upgrade" my custom installed netatalk 2.0.3-11+lenny1 to the standard (no SSL) 2.0.3-11+lenny1. Is anyone else seeing this behavior?

    • Tony

      I went ahead and updated the tutorial. I forgot to include instructions on changing the version number of netatalk, and placing a hold on the package to prevent upgrades from taking place. Please review the section on building / installing netatalk for the additions.

      Thanks for reminding me !!

  • Matthew

    This is the coolest! Man the internet computers! Thank you so much for this excellent walk through!

  • akess

    Verra nice walkthrough. Worked wonderfully.

  • MrtN

    Thanks for the tutorial!

    Mac OS X Lion complained when I tried to connect to my Debian AFP volume: "The version of the server you are trying to connect to is not supported. Please contact your system administrator to resolve the problem." After I compiled Netatalk 2.2.0 (without LDAP) on my Debian server, it worked like a charm. However, the volumes config file is now located at /usr/local/etc/netatalk/AppleVolumes.default .

  • Deby

    Hello, and thanks for the walk through. Unfortunately, I don't manage to connect to my Debian Box using afp via "Connect to Serveur"; I'm asked a Uid and PW and then an error message pops up (code -5002). Any ideas what I could do ? Is there anything I can do to debug the installation step by step?

  • Jaime Piña

    I couldn't find «cracklib2-dev». I did find «libcrack2-dev» however.

    This talks about the differences between: dbd, cdb, tdb, last.

    The «cdb» option no longer valid, according to the AppleVolumes.default file.
    You decided to use «dbd», based on the article above.

    Also, if you get this:
    «The version of the server you are trying to connect to is not supported.
    Please contact your system administrator to resolve the problem.»

    then replace this,
    – -transall -uamlist, -nosavepassword -advertise_ssh

    with this.
    – -tcp -noddp -uamlist,

    This is so cool!!!
    I got this to work with the following versions of software.
    Mac OS 10.8.2
    Debian 6.0, Squeeze
    Netatalk 2.1.2

  • mark

    I got most of this to work with MacOS 10.8.2, Debian 6.0 Squeeze and Netatalk 2.1.2 .
    By that I mean I can mount volumes from the Debian server on the Mac via AFP, however, Timemachine is not seeing the network drives even though I have run
    defaults write TMShowUnsupportedNetworkVolumes 1
    as suggested.
    has anyone else got this to work for time machine?

    • ChristianDESY

      I ran into the same problem and did the following:

      #### Line taken from
      /data/timemachine DebianTimeMachine allow:chris cnidscheme:dbd options:usedots,upriv,tm


      /etc/init.d/netatalk restart

      I could then see the volume when selecting the volume in timemachine. When selecting the volume "DebianTimeMachine" I was asked for credentials. After entering backup started.

      I am using a self-built netatalk
      ii netatalk 2.2.2-2 SSL i386
      and Macos 10.8.3 on the client

      Note, I did not mount the volume. It was just there, although I have my credentials for the server stored in the keychain (Not sure whether this is necessary or not).

      I wanted to say: Thank you for this very good tutorial. It is nice that all the steps are actually working, not so common in linux tutorials.

      • Preso

        Check that AppleVolumes.default file contains the "tm" option flag.

        /mnt/TimeMachine TimeMachine allow:USERNAME cnidscheme:dbd options:usedots,upriv,tm

  • rolandow

    It works, but it's loading my mp3 list really slow.. while listing contents on the linux box with ls, it's fast enough .. any suggestions?

  • thatGuy

    Is there a way to build netatalk with ldap on ubuntu 12.04? Has anyone accomplished this?