1. Overview
  2. Initialize a target
  3. Install iSCSI initiator
  4. Configure the initiator
  5. Issues
  6. Sparse Files


Apple Time Machine is a backup mechanism which uses an Apple sparse 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.

NetBSD does not support HFS+ 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, or SMB, or AFP (Apple File Protocol) through either the built-in facilities of mount_nfs(8), mount_smbfs(8) or a package like netatalk. These are all provided by userspace daemons.

If you want to use these, there are documented ways to do this, such as the 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.

defaults write TMShowUnsupportedNetworkVolumes 1

However, the NetBSD 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 file, in the NetBSD filesystem tree.

iSCSI talks about targets (which is what a provider of an iSCSI disk is) and initiators (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(8) daemon. The client has to have an initiator, which can present the target as a device.

In order to use this on OSX, you need an iSCSI initiator. One which is freely available is Studio Network Solutions globalSAN iSCSI initiator for OSX. At the time of writing, the version which works for me on Snow Leopard is which is distributed as a ZIP'ed DMG file.

Initialize a target

To create a target, you edit the targets(5) file.

The default example shipped with NetBSD 5.0 and later found in /etc/iscsi/targets is:

# Structure of this file:
# + an extent is a straight (offset, length) pair of a file or device
#   it's the lowest common storage denominator
#   at least one is needed
# + a device is made up of one or more extents or other devices
#   devices can be added in a hierachical manner, to enhance resilience
# + in this example, no device definitions are necessary, as the target
#   will just use a simple extent for persistent storage
# + a target is made up of 1 or more devices
# The code does not support RAID1 recovery at present

# Simple file showing 1 extent, mapped straight into 1 target 

# extent        file or device          start           length
extent0        /tmp/iscsi-target0      0               100MB

# target        flags   storage         netmask
target0         rw      extent0

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 below.)

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.

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.

Once you have configured a target, you need to enable and start the iscsi-target(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)

Install iSCSI initiator

  1. fetch the DMG, mount, install (reboot required)

Configure the initiator

  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.
  2. select the '[Targets]' tab and use the [+] button to add a new target.
  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.
  4. select 'Header Digest' by default
  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.
  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.

If you look at this disk image on the target, its interesting:

$ ls -ltr /tmp/iscsi-target0 
-rw-r--r--  1 root  wheel  104857600 Nov 18 22:45 /tmp/iscsi-target0

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.

$ file /tmp/iscsi-target0 
/tmp/iscsi-target0: x86 boot sector; partition 1: ID=0xee, starthead 254, startsector 1, 204799 sectors, extended partition table (last)\011, code offset 0x0


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...

Thats it! You can enable automatic mounting, or not (as you please) in the globalSAN preferences pane.

Once this is completed, the disk is a normal SCSI device, in HFS+ mode, and can be configured for any operation including Time Machine.


Sparse Files

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.

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(1) is safe or not. rsync has the -S flag to preserve sparse files.