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

1.2     ! schmonz     1: **Contents**
        !             2: 
        !             3: [[!toc]]
        !             4: 
        !             5: #  Overview 
        !             6: 
        !             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.se/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. 
        !             8: 
        !             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 [mount_nfs](http://netbsd.gw.com/cgi-bin/man-cgi?mount_nfs++NetBSD-5.0), [mount_smb](http://netbsd.gw.com/cgi-bin/man-cgi?mount_smbfs++NetBSD-5.0) or a package like [netatalk](http://pkgsrc.se/net/netatalk). These are all provided by userspace daemons. 
        !            10: 
        !            11: If you want to use these, there are documented ways to do this, such as the [apple time machine freebsd in 14 steps](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. 
        !            12:     
        !            13: defaults write com.apple.systempreferences TMShowUnsupportedNetworkVolumes 1
        !            14:     
        !            15: 
        !            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.se/How_to_use_iSCSI_to_support_an_Apple_Time_Machine#Sparse_Files) file, in the NetBSD filesystem tree. 
        !            17: 
        !            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 [iscsi-target][23] daemon. The client has to have an initiator, which can present the target as a device. 
        !            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: 
        !            24: To create a target, you edit the [/etc/iscsi/target](http://netbsd.gw.com/cgi-bin/man-cgi?targets+5+NetBSD-5.0) file. 
        !            25: 
        !            26: The default example shipped with NetBSD 5.0 and later is: 
        !            27:     
        !            28:     # $NetBSD: how_to_use_iscsi_to_support_an_apple_time_machine.mdwn,v 1.1 2011/11/20 20:55:21 mspo Exp $#
        !            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:   
        !            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.se/How_to_use_iSCSI_to_support_an_Apple_Time_Machine#Sparse_Files) below.) 
        !            52: 
        !            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. 
        !            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: 
        !            57: Once you have configured a target, you need to enable and start the [iscsi-target](http://netbsd.gw.com/cgi-bin/man-cgi?iscsi-target++NetBSD-5.0) 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) 
        !            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: 
        !           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 [pax](http://netbsd.gw.com/cgi-bin/man-cgi?pax++NetBSD-5.0) is safe or not. [rsync](http://pkgsrc.se/net/rsync) has the -S flag to preserve sparse files. 
        !           105: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb