Document that Syncthing may need extra permissions to access some paths on macOS

[Joshfindit]

Does your log mention database corruption?

No

Required information

• which version of Syncthing and what operating system you are using
  • macOS 12.3
• browser and version, if applicable
  • N/A
• what happened
  1. Browsed to the install and auto instructions ( https://docs.syncthing.net/users/autostart.html#macos )
  2. Ran brew install syncthing
     • It was successful. I got the following prompt:

       To start syncthing now and restart at login:
       brew services start syncthing
       

  3. brew services start syncthing => ==> Successfully started syncthing (label: homebrew.mxcl.syncthing)
  4. Configured it in the WebUI and added my device
  5. Had consistent errors in the UI:
     • Failed to create path for auto-accepted folder ... operation not permitted
     • Failed to create older root directory mkdir ... operation not permitted
     • Error on folder ... folder path missing
  6. Attempted troubleshooting by creating folders and changing folder/file permissions. This did change the errors, which felt like progress.
  7. Attempted troubleshooting by stopping the service and starting syncthing in terminal. This worked, which makes sense now but was confusing at the time.
  8. Found https://forum.syncthing.net/t/scanner-operation-not-permitted/15329 and gave the service full disk permissions. This solved it
• what you expected to happen instead
  • Expected To start syncthing now and restart at login: to be followed by After it starts, you will likely have to allow full disk permissions in "macOS Peferences" > "Security" > “full disk access”
  • Alternately, having it documented on https://docs.syncthing.net/users/autostart.html#macos
  • Further possibility: Clearly state the permission issue in the Web UI. Have you allowed disk access in the Security tab?
• any steps to reproduce the problem
  • See above

[calmh]

We don't maintain the brew installer or messages, you should probably inquire in the brew issue tracker.

[Joshfindit]

@calmh Thank you, I’ll follow up on that side about the brew messages.

Is there anything that can/should be done in terms of the official documentation?

[calmh]

Maybe a link somewhere to whatever Apple documentation exists on allowing applications to access files. I don't know where or what that would be. I don't think it's related to auto-start as such; double-clicking the binary should have the same effect as auto-starting it using launch control.

[acolomb]

@Joshfindit I guess you're welcome to open a Pull Request and propose text to be added to the documentation. Should come from someone who actually has regular access to a Mac and can verify the procedure. Few of the maintainers qualify in that regard I'm afraid.

I'd agree that neither the Web GUI nor the autostart section would be a good place for this though. Maybe best on https://docs.syncthing.net/intro/getting-started.html or as a FAQ?

[Joshfindit]

Thank you both for the guidance

double-clicking the binary should have the same effect as auto-starting it using launch control

It unfortunately does not:

• Running it by double-clicking it runs it in the default terminal
• Running it in the terminal (manually or by double-clicking) grants it the permissions of the terminal app (which most likely already has full disk access because it's very annoying to use terminal without it)
• Running it as a service requires that the binary has the required permissions

I think that given this macOS-specific information, it would be helpful to have a note in both https://docs.syncthing.net/intro/getting-started.html (In the 'Installing' subheading, or within a new subheading for example 'Permissions') and https://docs.syncthing.net/users/autostart.html#macos

I'd be happy to submit the PR for either/both.