netatalk.io

search netatalk.io

powered by DuckDuckGo

Troubleshooting

Netatalk Troubleshooting

Problem: I edit afp.conf but the new options aren’t taking effect.

Potential solution: Netatalk might be reading afp.conf from a different location. Run netatalk -V and compare the path that Netatalk expects.

AppleTalk Troubleshooting

Getting the AppleTalk (DDP) transport layer working in modern environments can often be a steep hill to climb. This guide provides a few pointers for resolving common pitfalls.

Before reading this guide, please read through the AppleTalk chapters in the manual for basic usage and setup.

The basic troubleshooting steps are:

  1. Launch atalkd and make sure it starts without error. If it errors out, kernel support for AppleTalk networking may be missing. (See the next section.)
  2. Run nbplkup and validate that the workstation names have been registered, e.g. for a host with hostname pretrix:
                        pretrix:netatalk                           65280.230:4
                        pretrix:Workstation                        65280.230:4
  1. If step 2 fails, wait a minute and try again. It takes a while for atalkd to stabilize.
  2. Make sure appletalk = yes is set in Global settings in afp.conf, then launch netatalk. If Netatalk is already running, shut it down first at this point.
  3. Wait a few seconds for the AFP server to fully start, then re-run nbplkup and validate that the AFPServer has been registered.
                        pretrix:AFPServer                          65280.230:130
                        pretrix:netatalk                           65280.230:4
                        pretrix:Workstation                        65280.230:4
  1. Now boot your vintage Mac that can speak AppleTalk and connect it to the network. When you run nbplkup, you should see both the old Mac and the Netatalk host.
                     PowerMacG4:AFPServer                          2601.2:251
                     PowerMacG4:  Power Macintosh                  2601.2:252
                     PowerMacG4:Workstation                        2601.2:4
                        pretrix:AFPServer                          65280.230:130
                        pretrix:netatalk                           65280.230:4
                        pretrix:Workstation                        65280.230:4
  1. When your network is in this state, open up Chooser on the old Mac, pick the AppleShare plugin, and you should see the Netatalk AFP server listed.

AppleTalk Kernel Module

Netatalk relies on AppleTalk support in the kernel to make use of the DDP layer. The atalkd daemon, which is part of the Netatalk package when built with AppleTalk support, will attempt to dynamically load the kernel module if not detected, and error out if all attempts fail. You can still use the DSI layer (TCP/IP) without an AppleTalk kernel module.

At the time of writing, Linux and NetBSD are known to have officially maintained AppleTalk kernel modules. Most major Linux distributions provide the AppleTalk kernel module by default, but others may need user intervention to enable.

For further discussion on how to work with the kernel module, see AppleTalk Kernel Module.

AppleTalk networking

Once you’ve confirmed that the OS kernel can speak AppleTalk, the next step is to get AppleTalk routing up and running.

The simplest scenario is when no other AppleTalk router exists on the local network, and a host computer with only one network interface. See the atalkd.conf manual page for an overview to how atalkd behaves when starting up.

If AppleTalk networking doesn’t work out of the box (not visible in the Chooser), try the following steps.

First off, you want to make sure that atalkd starts up fully before the other Netatalk daemons. The atalkd daemon can take a minute or longer to be fully available to register AppleTalk services.

Whenever you need to validate the current state, run the nbplkup command and validate that the default workstation services are registered.

Next up, you want to make sure that routing is working between the two machines you’re trying to network. Obviously, you first need an Ethernet to LocalTalk bridge of some sort for the Netatalk host and classic Mac to communicate. This is out of scope for this guide. A Classic Mac OS machine will also register a default workstation name (usually the model name for that Mac) that will be visible on the AppleTalk network.

If you run nbplkup on the Netatalk host machine, you should see both the Netatalk workstation and the classic Mac workstation. This is proof that routing is functioning correctly.

If this doesn’t work, you want to make sure that the configuration in atalkd.conf matches the correct network interface (especially when you have many interfaces and/or bridges available.) And if you have other AppleTalk routers on the network, you may have to disable routing on your local atalkd instance.

You want to make sure that AppleTalk traffic is not routed over WiFi, unless you know for a fact that your WiFi router explicitly handles AppleTalk packages (e.g. Apple AirPort or other early 2000s routers marketed as AppleTalk compatible.)

Sharing a modern printer over AppleTalk

Note that for this to work, your printer must be CUPS (Apple AirPrint) compatible. At the time of writing, the majority of modern printers are compatible. You can test this by piping some text to lp. First, list the printers that CUPS can see, then configure the default printer (HP Tango in the following example), finally pipe a stream to lp for printing.

$ lpstat -p -d
printer HP_Tango_333AB4_ is idle.  enabled since Fri 07 Jan 2022 06:47:09 PST
system default destination: HP_Tango_333AB4_
$ lpoptions -d HP_Tango_333AB4_
device-uri=ipps://HP%20Tango%20%5B333AB4%5D._ipps._tcp.local/ printer-info='HP Tango [333AB4]' printer-location printer-make-and-model='HP Tango' printer-type=16781324
$ echo "NETATALK IS AWESOME" | lp
request id is HP_Tango_333AB4_-3 (0 file(s))

The next step is to configure papd. Edit /etc/netatalk/papd.conf and add the following line to the bottom of the file:

cupsautoadd:op=root:

Save, exit, and restart papd.

At this stage, you want to test that the CUPS printer is shared over AppleTalk. This can be done using this command:

$ nbplkup

The output should look something like this:

                     rascsi3b:ProDOS16 Image                     65280.205:3
             HP Tango 333AB4 :LaserWriter                        65280.205:130
                     rascsi3b:Apple //e Boot                     65280.205:3
                     rascsi3b:AFPServer                          65280.205:131
                     rascsi3b:TimeLord                           65280.205:129
                     rascsi3b:Apple //gs                         65280.205:3

If you see your printer here, the only thing left is to configure the printer on your vintage Mac in the Chooser. This part may vary depending on AppleTalk version, printer drivers on your system, and model and make of printer. The author has tested their HP Tango printer with LaserWriter 7 on System 7.1.1, and LaserWriter 8 on Mac OS 8.6:

  1. Pick the LaserWriter driver in the Chooser. Your printer should appear in the list of PostScript printers.
    1. If using LaserWriter 7 or earlier, just selecting the printer should be enough.
    2. If using LaserWriter 8, click Setup.
  2. When given the option to pick PPD (printer description file) choose plain LaserWriter from the list.
  3. Print!

If printing doesn’t immediately work, try experiment with other stock PPD files in the Chooser, or track down 3rd party ones that may be compatible, and see it that makes a difference.

Footnotes

This is a mirror of the Netatalk GitHub Wiki. Please visit the original page if you want to correct an error or contribute new contents.

Last updated 2025-04-19

Valid HTML5 Valid CSS

Netatalk and the Netatalk website are licensed under the GNU General Public License 2.0.