Skip to content

FAQ.md

Latest commit

 

History

History
186 lines (121 loc) · 7.42 KB

FAQ.md

File metadata and controls

186 lines (121 loc) · 7.42 KB

Frequently Asked Questions (FAQ)

General Questions

What Time Capsule models are supported?

Gen 5 Time Capsules - fully supported with automatic startup Time Capsule Model

Gen 1-4 Time Capsules - supported with manual activation after each reboot

What AirPort Extreme models are supported?

AirPort Extreme models with attached USB storage are supported by the same deploy/runtime model, but they are less broadly validated than Time Capsule hardware. Use tcapsule configure and tcapsule doctor to confirm the specific device.

Is this safe to use?

Yep. This doesn't touch anything that will permanently brick a Time Capsule. This also does not delete any of your previous data.

Setup and Configuration

What is the "Device Password" mode?

TimeCapsuleSMB needs the device/root password during setup. That password is used to enable or access SSH and is also used to generate the managed Samba password.

AirPort Utility commonly exposes this as "With device password" under disk sharing. This project does not validate the AirPort disk-sharing mode directly, but using the device password mode keeps the password model aligned with what tcapsule configure expects.

To check/change this:

  1. Open AirPort Utility on your Mac
  2. Select your Time Capsule
  3. Go to the "Disks" tab
  4. Look for the "Secure Shared Disks" setting
  5. Ensure it's set to "With device password" mode

The device password you enter during setup becomes the SMB password.

Do I need to keep the TimeCapsuleSMB folder after setup?

Yes, it is recommended to keep the TimeCapsuleSMB folder on your Mac for maintenance purposes. While you can delete it after initial setup, keeping it allows you to:

  • Run tcapsule doctor to diagnose issues
  • Run tcapsule fsck to repair the disk
  • Run tcapsule activate after reboots (for Gen 1-4 NetBSD 4 devices)
  • Run tcapsule uninstall if you want to remove it from the Time Capsule

The folder contains all the scripts, binaries, and configuration files needed for ongoing maintenance.

How do I connect to the Time Capsule after setup?

Once deployment is complete, you can connect via:

  • Finder: Look in the "Network" folder
  • Direct URL: smb://<advertised-host>.local/<share-name> or smb://<yourtimecapsuleIP>/<share-name>

Credentials:

  • Username: admin in the docs/examples. The managed Samba config maps incoming SMB usernames to Unix root.
  • Password: Your Time Capsule password

Do I need to uninstall before updating?

No. You can run deploy over an old deployment.

Troubleshooting

I'm not sure what went wrong

  1. Reboot the device
  2. Do a fresh deploy on top of the (maybe corrupt) old deploy

A reboot and clean deploy will fix 90% of issues. This is especially useful for old Gen 1-4 devices, because their firmware usually does not provide remote scp, so uploads use a slower SSH fallback. The deploy flow verifies uploaded file sizes, but rerunning deploy is still the simplest way to replace any interrupted upload.

Time Machine backups are broken on certain macOS versions

Time Machine network backups have known macOS-side regressions on macOS 26.4.x and macOS 15.7.5-15.7.7. See this Cult of Mac report and this later MacObserver report about a 26.5 beta fix for context.

Workaround: Macs running these versions can still use the device as a standard Samba network share in Finder, but Time Machine backups will not work properly. You can also try the workaround mentioned in the article.

The Time Capsule doesn't show up in Finder

  1. Try connecting directly:

    smb://<advertised-host>.local/<share-name>

  2. Use the IP address from your .env file if hostname resolution fails:

    smb://<yourtimecapsuleIP>/<share-name>

I get "Error 22" or "Invalid Argument" errors

Error 22 / Invalid Argument errors usually indicate disk corruption.

To fix this:

  1. Run the disk repair command:

    .venv/bin/tcapsule fsck

  2. If fsck doesn't resolve the issue, you may need to:

    • Back up your data if possible
    • Erase the disk using Apple AirPort Utility
    • Re-run the TimeCapsuleSMB setup

My Gen 1-4 device is not working after every reboot

This is normal for NetBSD 4 devices (older Gen 1-4 Time Capsules). The firmware doesn't persist the /etc boot hook needed to auto-start Samba.

Solution: Always run tcapsule activate after rebooting older devices.

Security and Privacy

Is this secure?

It's probably fine for a home network, but if you're very sensitive about security this is not the software for you. Use at your own risk. It's using a build of Samba 4.24.1 currently.

What files are added to the Time Capsule?

The deploy script installs files in:

  • /mnt/Flash on the Time Capsule (boot files)
    • /mnt/Flash/rc.local
    • /mnt/Flash/start-samba.sh
    • /mnt/Flash/watchdog.sh
    • /mnt/Flash/common.sh
    • /mnt/Flash/dfree.sh
    • /mnt/Flash/mdns-advertiser
    • /mnt/Flash/tcapsulesmb.conf
    • These files are created by mdns-advertiser
      • /mnt/Flash/allmdns.txt
      • /mnt/Flash/applemdns.txt
  • .samba4 folder on the root of the hard drive (Samba files). This is the fixed managed payload folder name.

All other files/folders are stored on ramdisks and will be deleted after a reboot.

The uninstall script removes these managed files and optionally reboots the device.

Getting Help

Where can I get help?

If you find any problems, please file an issue here. The developer is actively working on improvements.

What information should I include when reporting issues?

When filing an issue, please include:

  1. Your Time Capsule model
  2. macOS version you're using
  3. Output of tcapsule doctor
  4. Any error messages you're seeing
  5. Steps to reproduce the problem

Advanced Topics

Can I rebuild the binaries myself?

Yes! If you want to rebuild smbd yourself, run the scripts in build/ on a NetBSD machine. The binaries are statically compiled, so you don't need anything else on the Time Capsule.

Can I customize the configuration?

Only a small set of local configuration is managed now:

  • device host
  • device/root password
  • legacy SSH options
  • the hidden internal-disk share-root behavior

Share names and Bonjour names come from the Time Capsule itself. For most users, the defaults are recommended.

Maintenance

How do I update TimeCapsuleSMB?

To update to a newer version:

  1. git pull in the TimeCapsuleSMB folder
  2. Run tcapsule deploy again
  3. Run tcapsule doctor to verify

How do I completely remove TimeCapsuleSMB?

To remove TimeCapsuleSMB:

.venv/bin/tcapsule uninstall

This removes the managed payload and boot files. After a reboot, your Time Capsule will be restored to its factory condition (though Apple SMB/AFP settings may vary).

What if I want to keep the project folder but remove it from my Mac?

The deployed runtime can keep working without the local TimeCapsuleSMB folder, because the managed runtime files are stored on the Time Capsule. Keep the local folder if you want to update, redeploy, run doctor, run fsck, activate older Gen 1-4 devices, or uninstall cleanly.