Annotation of wikisrc/tutorials/how_to_use_iscsi_to_support_an_apple_time_machine.mdwn, revision 1.6

1.2       schmonz     1: **Contents**
                      2: 
                      3: [[!toc]]
                      4: 
                      5: #  Overview 
                      6: 
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:     
                     15: 
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 3.3.0.43 which is distributed as a ZIP'ed DMG file. 
                     21: 
                     22: #  Initialize a target 
                     23: 
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:
                     30:     #
                     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
                     40:     
                     41:     # Simple file showing 1 extent, mapped straight into 1 target 
                     42:     
                     43:     # extent        file or device          start           length
                     44:     extent0        /tmp/iscsi-target0      0               100MB
                     45:     
                     46:     # target        flags   storage         netmask
                     47:     target0         rw      extent0         0.0.0.0/0
                     48:     
                     49: 
                     50:   
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. 
                     56: 
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: 
                     59: 
                     60: #  Install iSCSI initiator 
                     61: 
                     62:   1. fetch the DMG, mount, install (reboot required) 
                     63: 
                     64: #  Configure the initiator 
                     65: 
                     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. 
                     72: 
                     73: If you look at this disk image on the target, its interesting: 
                     74:     
                     75:     $ ls -ltr /tmp/iscsi-target0 
                     76:     -rw-r--r--  1 root  wheel  104857600 Nov 18 22:45 /tmp/iscsi-target0
                     77:     
                     78: 
                     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. 
                     80:     
                     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
                     83:     
                     84:     $
                     85:     
                     86: 
                     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... 
                     88: 
                     89: Thats it! You can enable automatic mounting, or not (as you please) in the globalSAN preferences pane. 
                     90: 
                     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. 
                     92: 
                     93: #  Issues 
                     94: 
                     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. 
                     99: 
                    100: #  Sparse Files 
                    101: 
                    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. 
                    103: 
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