Annotation of wikisrc/tutorials/how_to_use_iscsi_to_support_an_apple_time_machine.mdwn, revision 1.6
1.2 schmonz 1: **Contents**
5: # Overview
1.3 sevan 7: [Apple Time Machine](http://www.apple.com/macosx/what-is-macosx/time-machine.html) is a backup mechanism which uses an Apple [sparse](http://wiki.netbsd.org/how_to_use_iscsi_to_support_an_apple_time_machine#Sparse_Files) filesystem model, with extended attributes to store the files and directories of your OSX system as an incremental state. You can walk 'back in time' against the history of the filesystem and recover older versions of files, or files which have subsequently been deleted. Unlike a dump, its not a complete independent collection of files: it prunes back in time against what it knows has changed, and so cannot be relied on in the same way as offline disk or tape backup written in a rigorous system. Nor is it an archive: if you want to preserve something, you need to manage that independently of a time machine setup. But, having said that, its enormously useful and very user friendly, and lots of OSX users are very happy with it. Most of them use directly attached media like a firewire or USB disk, or an Apple appliance like the Time Capsule. However, it is technically possible to do Time Machine over a network, to a network-mounted filesystem.
1.2 schmonz 8:
1.3 sevan 9: NetBSD does not support [HFS+](http://en.wikipedia.org/wiki/HFS_Plus) format filesystems directly in a way which can be exposed to an OSX host over the network. Normally, its UNIX filesystems are mounted on clients by protocols like [NFS](http://en.wikipedia.org/wiki/Network_File_System_%28protocol%29), or [SMB](http://en.wikipedia.org/wiki/Server_Message_Block), or [AFP](http://en.wikipedia.org/wiki/Apple_Filing_Protocol) (Apple File Protocol) through either the built-in facilities of [[!template id=man name="mount_nfs" section="8"]], [[!template id=man name="mount_smbfs" section="8"]] or a package like [netatalk](http://pkgsrc.se/net/netatalk). These are all provided by userspace daemons.
1.2 schmonz 10:
1.4 sevan 11: If you want to use these, there are documented ways to do this, such as the [apple time machine freebsd in 14 steps](https://web.archive.org/web/20081008055929/http://blogs.freebsdish.org/rpaulo/2008/10/04/apple-time-machine-freebsd-in-14-steps/) page Rui Paulo wrote. They each have advantages and disadvantages, noting the need for special file support and extended attributes. Its probable that making the correct Apple sparse filesystem as a single file image, and moving this to the network-backed filestore gets round most of the problems, if you set the correct magic flag in your OSX to permit non-standard filesystems to be used to 'home' the time machine.
1.2 schmonz 12:
1.4 sevan 13: defaults write com.apple.systempreferences TMShowUnsupportedNetworkVolumes 1
1.2 schmonz 14:
1.3 sevan 16: However, the NetBSD [iSCSI](http://en.wikipedia.org/wiki/ISCSI) implementation is robust, and efficient, and will provide arbitrary client-side filesystems (such as HFS+, or Windows filesystems) because its presenting SCSI disk as raw blocks. These raw blocks are typically provided from a [sparse](http://wiki.netbsd.org/how_to_use_iscsi_to_support_an_apple_time_machine#Sparse_Files) file, in the NetBSD filesystem tree.
1.2 schmonz 17:
1.6 ! sevan 18: iSCSI talks about [targets](http://en.wikipedia.org/wiki/ISCSI#Target) (which is what a provider of an iSCSI disk is) and [initiators](http://en.wikipedia.org/wiki/ISCSI#Initiator) (which is what a client connecting to a given target is). -In this situation, NetBSD will be running as the target, via the [[!template id=man name="iscsi-target" section="8"]] daemon. The client has to have an initiator, which can present the target as a device.
1.2 schmonz 19:
20: In order to use this on OSX, you need an iSCSI initiator. One which is freely available is Studio Network Solutions [globalSAN iSCSI initiator](http://www.studionetworksolutions.com/products/product_detail.php?t=more&pi=11) for OSX. At the time of writing, the version which works for me on Snow Leopard is 184.108.40.206 which is distributed as a ZIP'ed DMG file.
22: # Initialize a target
1.3 sevan 24: To create a target, you edit the [[!template id=man name="targets" section="5"]] file.
1.2 schmonz 25:
1.3 sevan 26: The default example shipped with NetBSD 5.0 and later found in `/etc/iscsi/targets` is:
1.2 schmonz 27:
1.3 sevan 28: #
1.2 schmonz 29: # Structure of this file:
31: # + an extent is a straight (offset, length) pair of a file or device
32: # it's the lowest common storage denominator
33: # at least one is needed
34: # + a device is made up of one or more extents or other devices
35: # devices can be added in a hierachical manner, to enhance resilience
36: # + in this example, no device definitions are necessary, as the target
37: # will just use a simple extent for persistent storage
38: # + a target is made up of 1 or more devices
39: # The code does not support RAID1 recovery at present
41: # Simple file showing 1 extent, mapped straight into 1 target
43: # extent file or device start length
44: extent0 /tmp/iscsi-target0 0 100MB
46: # target flags storage netmask
47: target0 rw extent0 0.0.0.0/0
1.3 sevan 51: The target should be the name of a file in the filesystem you want it to reside in. When the iscsi-target daemon first runs over this configuration, targets are initialized as UNIX sparse files. Be very careful *not* to touch this file with a cp or any other operation which tickles NetBSD into filling in the 'holes' in the sparce file: dump and tar should be safe, as is rsync if the -S flag is given to it. (see [sparse files](http://wiki.netbsd.org/how_to_use_iscsi_to_support_an_apple_time_machine#Sparse_Files) below.)
1.2 schmonz 52:
1.3 sevan 53: The `/etc/iscsi/target` file can implement simple ACL models for the IP network/prefix of the client(s) you wish to permit. The default in this file as distributed is a fully open iSCSI target. There is an associated `/etc/iscsi/auth` file which can be used to instantiate CHAP and other protections over the iSCSI attachment by the client.
1.2 schmonz 54:
55: Be warned that the target name *has* to include a digit which will be translated to the SCSI 'LUN' number of the device for the client. Unless you know what you are doing, its best to leave this as 0 since the client may well demand only LUN0 is used.
1.6 ! sevan 57: Once you have configured a target, you need to enable and start the [[!template id=man name="iscsi-target" section="8"]] daemon. Edit `/etc/rc.conf` and enable `iscsi-target=YES`, and then you can run `/etc/rc.d/iscsi_target start` (it will start automatically on reboot once enabled in `/etc/rc.conf`)
1.2 schmonz 58:
60: # Install iSCSI initiator
62: 1. fetch the DMG, mount, install (reboot required)
64: # Configure the initiator
66: 1. open 'System Preferences' and select globalSAN. It will throw a warning about restart. Don't worry, it just flicks you to the correct system Preference pane.
67: 2. select the '[Targets]' tab and use the [+] button to add a new target.
68: 3. provide the name or IP address of your NetBSD iSCSI target. If you didn't alter the port it serves from, don't alter the port here.
69: 4. select 'Header Digest' by default
70: 5. enable the mount. This will cause OSX to detect a new (raw) device, and ask you what to do with it. You should select [Initialize...] to enter the OSX 'disk utilities' pane. OSX is then initializing this SCSI LUN over the wire, using the iSCSI protocol to read and write the disk blocks. If you have a large back-end iSCSI target file, this operation will take quite a long time: its really just like newfs on a real raw disk, except its done a) over a network protocol and b) into a single file on the host/target filesystem.
71: 6. in Disk Utilities you can use any Volume Scheme you like. I selected one partition, of HFS+ with journalling. This is what a locally attached USB or firewire external disc is typically configured as, but 'its just a disk' -you can sub partition it any way you like.
73: If you look at this disk image on the target, its interesting:
75: $ ls -ltr /tmp/iscsi-target0
76: -rw-r--r-- 1 root wheel 104857600 Nov 18 22:45 /tmp/iscsi-target0
79: It reports as a large file (the 100mb of the /etc/iscsi/target file) but, its not. DF on the filesystem will show its not all occupied.
81: $ file /tmp/iscsi-target0
82: /tmp/iscsi-target0: x86 boot sector; partition 1: ID=0xee, starthead 254, startsector 1, 204799 sectors, extended partition table (last)\011, code offset 0x0
87: Its detected as a file which contains a boot sector and disk structure. In principle you could probably use vnconfig to mount and examine this file. Not advised if its being served by an iscsi-target daemon...
89: Thats it! You can enable automatic mounting, or not (as you please) in the globalSAN preferences pane.
91: Once this is completed, the disk is a normal SCSI device, in HFS+ mode, and can be configured for any operation including Time Machine.
93: # Issues
95: * It can be slow. Bear in mind that the speed you get for iSCSI is strongly limited by the client's ethernet speed, and any switching fabric you have. Real SAN use dedicated high speed switches and protocols like infiniband to maximise disk throughput. if you do iSCSI on a home network, its not going to look like your corporate SAN at work.
96: * Wireless is a poor choice of network to initialize your time-machine backup on: in my case, the first dump is 160GB (!) and this would not complete in a sensible time.
97: * Even on a wired network, a home router is going to throttle you. I had 100mbit on my server and 100mbit on my router-switch combo, and achieved throughput of the order 10GBytes/hr which is 2MBytes/sec. thats well below apparent switch speed. (I will be experimenting with back-to-back connection)
98: * raidframe also imposes speed constraints. I was using a software RAID of 1+0 over (notionally) 6 SATA disks, but two of the mirror-sets were running in 'degraded' mode.
100: # Sparse Files
102: A sparse file is a special file-type which reports its 'size' in ls -l as the total it could be, if it was fully populated. However, until actual file blocks at given offsets are written, they aren't there: its a linked list. This permits a very fast growable file to a limit, but at some risk: if you accidentally touch it the wrong way, it fills in the holes. You just have to be careful. FTP for instance, doesn't honour sparse files. if you copy a file with FTP, the holes are filled in.
1.5 sevan 104: Sparse files were implemented in UNIX FFS a long time ago, and are in HFS+ as well. The behaviour of the tools like pax, rsync, tar, ftp has to be verified on a case-by-case basis. Its not clear if NetBSD [[!template id=man name="pax" section="1"]] is safe or not. [rsync](http://pkgsrc.se/net/rsync) has the -S flag to preserve sparse files.
1.2 schmonz 105:
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb