Project

General

Profile

Feature #12780

FreeNAS Guide should be less obscure about client-side 'tweaks' for Time Machine users

Added by Graham Perrin almost 5 years ago. Updated almost 3 years ago.

Status:
Resolved
Priority:
No priority
Assignee:
Dru Lavigne
Category:
Documentation
Estimated time:
Severity:
New
Reason for Closing:
Reason for Blocked:
Needs QA:
Yes
Needs Doc:
Yes
Needs Merging:
Yes
Needs Automation:
No
Support Suite Ticket:
n/a
Hardware Configuration:

Description

Background: http://www.freenas.org/about/features.html

… supports Time Machine backups with a few minor tweaks on the system being backed up. …

That's relatively obscure. For that, I'll make a separate feature issue (website category).

http://www.freenas.org/t/ is more direct:

Mac users can use space on AFP or CIFS shares as targets for Time Machine backups.

https://doc.freenas.org/9.3/freenas_sharing.html#apple-afp-shares states:

To configure Time Machine on the Mac OS X client, go to System Preferences ‣ Time Machine which will open the screen shown in Figure 10.1g. Click “ON” and a pop-up menu should show the FreeNAS® system as a backup option. In our example, it is listed as backup_user1 on “freenas”. Highlight the entry representing the FreeNAS® system and click the “Use Backup Disk” button. A connection bar will open and will prompt for the user account’s password–in this example, the password that was set for the user1 account.

Unless I'm missing something, no tweaking there.

Is the reference to http://forum1.netgear.com/showthread.php?t=49482 treated as a tweak? (That's a workaround to an exceptional problem; not part of normal client-server operation.)

It should help to simply state whether service conforms to the Time Machine Server Requirements expressed in Apple's Time Machine Network Interface Specification (TMNIS) document for developers.

Re https://support.apple.com/HT201250#restore – and more specifically the Command-R part of OS X Mavericks: Recover your entire system – is FreeNAS recognised as a Time Machine server for restore purposes when a client machine boots Recovery OS (in lieu of OS X)? E.g. when restoring to a machine where the slice for OS X has been erased.

As background: in IRC I encountered doubt that non-Apple NAS could be as good as Apple NAS for Time Machine server purposes.

Associated revisions

Revision 799bd6b4 (diff)
Added by Dru Lavigne over 4 years ago

Remove deprecated statement. Fixes #12780.

Revision 3884a686 (diff)
Added by Dru Lavigne over 4 years ago

Remove deprecated statement. Fixes #12780.

History

#1 Updated by Dru Lavigne almost 5 years ago

  • Status changed from Unscreened to 15

Can you please clarify what you would like to see added to the documentation? Or is there a section that you feel is incorrect (if so, please paste the exact wording and what is incorrect).

#2 Updated by Dru Lavigne almost 5 years ago

Do you still want this change? If so, can you please clarify what text needs to change?

#3 Updated by Graham Perrin almost 5 years ago

Yep, I'll probably get to drafting text at the weekend.

In the meantime, from recent discussion in IRC:

<grahamperrin> … I'll suggest text. Just as a heads-up, I tested Time Machine client in OS X 10.9.5 with FreeNAS 9.x and (as I expected) it worked perfectly for beginning backups.

I assume that FreeNAS does conform to Apple's Time Machine Server Requirements but I have not yet tested whether a complete backup to FreeNAS results in something that can be recognised as a source, for restoration, by Time Machine in Recovery OS.
<grahamperrin> I also assume that the network restore + Recovery OS aspect is not within Apple's requirements.
<grahamperrin> Whilst uncertain about that I can at least write some text to clarify that the risk of problems such as https://community.netgear.com/t5/Stora-Legacy/Solution-to-quot-Time-Machine-could-not-complete-the-backup/td-p/294697 (currently linked from FreeNAS documentation) are inherent to Time Machine's use of HFS Plus.
<grahamperrin> OK, I'm off for a drive. dlavigne1 (and others), if you have any thoughts on that Time Machine stuff please leave something here (or in issue 12780) and I'll pick things up when I return. Thanks.

#4 Updated by Graham Perrin almost 5 years ago

… whether service conforms to the Time Machine Server Requirements …

http://lists.freenas.org/pipermail/freenas-devel/2016-January/001427.html asks the question.

#6 Updated by Dru Lavigne almost 5 years ago

Whoa, please slow down on the references :-) Instead, what I need clarity on is this: are the docs as written correct (eg, do they result in a working configuration)? If not, which sentences are incorrect (eg result in a failed configuration) and what text should they be replaced with (eg what specific instructions should be added to the Guide to fix the part that is not working). Ideally, that text will have been first tested to verify that it does indeed result in a working configuration.

#7 Updated by Graham Perrin almost 5 years ago

Sure, I'll get to the text tomorrow (Sunday); the reference gathering is for my own benefit. Last but not least:


Focusing on the ultimate and penultimate paragraphs under https://doc.freenas.org/9.3/freenas_sharing.html#creating-authenticated-and-time-machine-shares (before 10.2): when was it last reported that a server-side scrub caused a Time Machine client to find inconsistency at the HFS Plus level?

#8 Updated by Jordan Hubbard almost 5 years ago

I'm still confused by this myself. FreeNAS includes Netatalk with a limited number of configuration options. What is the user supposed to do with this information, specifically as it relates to the UI?

Personally, I have never had any trouble using FreeNAS with Time Machine (going back many releases) so I'm not sure what problem we are trying to solve? Is there some TM scenario that the documentation needs to explain how to configure FreeNAS for?

#9 Updated by Graham Perrin almost 5 years ago

Jordan Hubbard wrote:

… what problem …

Essentially:

  • repeated misinformation from people who are not suitably familiar with FreeNAS and/or ZFS.

When I first encountered that misinformation, I looked to the freenas.org domain for assuring/reassuring statements that should improve understanding of the goodness of FreeNAS as a Time Machine server. Goodness, readiness. I wished to draw attention to such statements, to end the misinformation.

The FreeNAS features page suggests that the user must make multiple tweaks to Mac OS X for compatibility with FreeNAS; that's not readiness.

I find no need for tweaks.


So I looked beyond those web pages, to the Handbook, to see what those tweaks might be.

Screenshots are from Mac OS X Lion, probably in 2011. Some of the related text may be similarly outdated. For example, the suggestion that inconsistency

can occur after performing a scrub

– that's not reassuring.

#10 Updated by Dru Lavigne almost 5 years ago

That sounds like a website bug (which is a different team). Did you make a separate bug for that or would you like me to assign it to the web team?

#11 Updated by Graham Perrin almost 5 years ago

If I recall correctly, around the time of https://bugs.pcbsd.org/issues/12760#note-5 (opened in the wrong project (sorry)) it was thought that it'll be better to attend to the documentation aspect before opening the separate issue for for website aspect. Pinging you now in IRC … :)

#12 Updated by Graham Perrin almost 5 years ago

Suggestion 1

Removal of the following sentence from the Guide:

Note that this can occur after performing a scrub as Time Machine may mistakenly believe that the sparsebundle backup is corrupt.

Notes:

If there truly is a bug that involves scrubbing, then it is IMHO extremely unlikely that the symptoms would be limited to Time Machine service. So … remove the sentence :)

#13 Updated by Dru Lavigne almost 5 years ago

Just to clarify, is that the only edit needed for the Guide for this ticket?

#14 Updated by Graham Perrin almost 5 years ago

A statement of conformance within the Guide to FreeNAS

Graham Perrin wrote:

… It should help to simply state whether service conforms to the Time Machine Server Requirements …

http://lists.freenas.org/pipermail/freenas-devel/2016-January/001428.html suggests yes (thank you, Jordan) but it seemed that the link to requirements was overlooked before that answer. Also, what follows might be contradictory:

… is FreeNAS recognised as a Time Machine server for restore purposes when a client machine boots Recovery OS …?

https://forums.freenas.org/index.php?threads/40308/ suggests not.

I'd like to test for myself, but the hardware that I normally use for FreeNAS failed a few days ago. (The replacement hardware will be ready after I obtain a few cables. Maybe a week from now.)

In the meantime: if what's outlined at http://netatalk.sourceforge.net/wiki/index.php/Bonjour_record_adisk_adVF_values suffices for Time Machine service to be found – as it is – for the purposes of initial and subsequent backups, then (off the top of my head) I can't think of any reason why the same service, with a suitably complete backup of OS X, would be not found by Recovery OS.


The Guide should not be open to misinterpretation; should not give readers the impression that FreeNAS is unreliable and/or a cause of corruption

If you receive the message “Time Machine completed a verification of your backups. To improve reliability, Time Machine must create a new backup for you.” and …

Within that paragraph there's no hint that the unreliability is, essentially, with Apple technologies. Discussion – of true causes, and of workarounds to the problems – is widespread enough for me to suggest that the Guide to FreeNAS need not mention reliability of Time Machine.

(The problems can happen with Apple products such as Time Capsule, and so on.)


Consider adding positive guidance about ZFS snapshots of the file system that includes the sparse bundle disk image(s) for Time Machine

https://forums.freenas.org/index.php?threads/35247/#post-257308 brings together some quotes. In a nutshell:

a) timely snapshots are easy to perform

b) if (in a problem situation) a Time Machine client treats the backup data as immutable, then emphasise ease of rollback – to a point in time when the sparse bundle disk image and HFS Plus file system were both good (or good enough)

c) the alternative to (a) + (b) is an fsck_hfs that may be monstrously time-consuming.

Would you like me to draft the guidance? (I'll need to remind myself of what happens when multiple clients back up to a single server.)


The Guide may contain redundant advice about manual creation of a sparse bundle disk image

If you receive a “Time Machine could not complete the backup. The backup disk image could not be created (error 45)” error when backing up to the FreeNAS® system, you will need to create a sparsebundle image using these instructions.

http://apple.stackexchange.com/a/39837/8546 was answered around five months before the release of Mac OS X Lion (10.7), at which time the author (iSALAM) found no need to manually create a .sparsebundle with ZFS in the mix. Locally attached, not NAS, still: it's significant. However it's not clear whether that answer related to Snow Leopard (10.6.x).

(Side note: https://en.wikipedia.org/wiki/OS_X_Mountain_Lion#History suggests that 10.7 became golden master on 2015-07-09; my edition http://apple.stackexchange.com/posts/39837/revisions was made a few days earlier. My AppleSeed archives show that seed testing probably began in March 2011 … it's vaguely possible that the February 2012 answer from iSALAM was a premature statement about Lion.)

Again: I'd like to test for myself. A nearby MacBookPro8,2 is currently unused, and can get OS X 10.7.5 with Internet Recovery, but the test with FreeNAS must wait until after replacement hardware is made good.


Generally

There's some ruthlessness by Apple in its read-only archiving of support articles for Mavericks (OS X 10.9.x).

An updated Guide for FreeNAS with Time Machine could be similarly ruthless, narrow – show only what's required for Yosemite (OS X 10.10.5) and greater – but personally, I like the broader support.

If the Guide is to exemplify use with Lion, then let's ensure that what's stated is true for the most recent release of FreeNAS :)

#15 Updated by Graham Perrin almost 5 years ago

Correction! I wrote:

The Guide may contain redundant advice about manual creation of a sparse bundle disk image

http://apple.stackexchange.com/a/39837/8546 was answered around five months before the release of Mac OS X Lion (10.7) …

Sorry! Ignore my confusion around dates. I was looking at the wrong page, Mountain Lion, in Wikipedia.

Truly relevant: https://en.wikipedia.org/wiki/Mac_OS_X_Lion#Release_and_distribution

… I'd like to test for myself.

#16 Updated by Graham Perrin over 4 years ago

… is FreeNAS recognised as a Time Machine server for restore purposes when a client machine boots Recovery OS …?

Yes. https://forums.freenas.org/index.php?threads/timemachine-cant-find-afp-share-in-recovery.40308/#post-261472 shows OS X Internet Recovery (10.7.5) Recovery OS Time Machine working wirelessly with FreeNAS 9.2-RELEASE-p9; the server was found.

The Guide may contain redundant advice about manual creation of a sparse bundle disk image

With OS X Internet Recovery I performed a clean installation of Mac OS X 10.7.5, ran Apple Software Update, restarted the OS and then used the Mac wirelessly with FreeNAS. Time Machine backups began and completed without difficulty; creation of the sparse bundle disk image was automated by Lion.


As a companion to this documentation issue we now have website issue #13411:

  • The FreeNAS features page should be positively assertive about compatibility with Apple Time Machine (tweaks are not required)

#17 Updated by Dru Lavigne over 4 years ago

  • Status changed from 15 to Resolved

See commit 799bd6b44c1b5e8459f183c13fd43d9e6d54a64e.

Note for future doc change requests: rather than including references and research, instead provide the desired reworded text in the bug report or issue a git pull request with the changed text. This makes it much easier to pinpoint what rewording is needed to clarify the issue and we can always ask for references if we are unsure if the rewording is correct.

#18 Updated by Graham Perrin over 4 years ago

#19 Updated by Dru Lavigne over 4 years ago

Weird. Can you see https://github.com/freenas/freenas/commit/799bd6b44c1b5e8459f183c13fd43d9e6d54a64e? That's the actual commit which was pushed to doc.pcbsd.org.

#20 Updated by Dru Lavigne almost 3 years ago

  • Target version set to Master - FreeNAS Nightlies

Also available in: Atom PDF