SHU SAN Scripts

Together these scripts define a store command, used to simplify the task of creating, deleting and managing iSCSI targets on OpenSolaris (Solaris > 11) based hosts. It has been tested on Nexenta NCP and Open Indiana, but with some modification it could be made to work on FreeBSD as well.

The user interface is deliberately as simple as possible: we assume the user has no underlying knowledge of (Open)Solaris, ZFS and not all that much of iSCSI. Instead the scripts aim to get iSCSI targets up and running as quickly as possible. Much more complex set-ups are indeed possible: see the relevant Oracle ZFS administrator’s guides for more inspiration.

Using the Scripts

Assuming Ruby Gems has been installed

gem install shu-san-scripts

should install everything you need. A brief summary of the commands available can be obtained by

store --help

once everything has been installed.

Note: The scripts assume they are running (or at least have access to) the root user role, as they will manipulate your ZFS volumes. You can either install them with the appropriate privileges, or install the sudo command to make life easier. With sudo

sudo store --help

should get you started.

Warning: We use these scripts in a teaching environment, and so we assume the host they are running on is somewhat disposable. Your needs may differ…

Synopsis

General help can be obtained by running store –help, or store with no arguments

A command-line tool for managing iSCSI targets on OpenSolaris.

Available commands:

    delete_vol           Remove the specified target from the iSCSI volume store.
    help                 Show help for a command
    list_vols            Show the currently defined iSCSI targets on this host.
    new_vol              Create a new iSCSI volume in the SAN volume store.

Global options:

    -h --help            show this help message and quit
    -C --no-color        disable color
    -V --verbose         make store command output more detailed
    -v --version         show version information and quit

Help on individual commands can then be obtained using the command as an argument to store help. For instance

# store help new_vol

produces

store new_volume [--volume-store ZFS_PATH][--name GUID] [--size INTEGER]

aliases: new add add_vol

Create a new iSCSI volume in the SAN volume store.

    By default, this command creates a 20G ZFS volume, and marks it for sharing
    as an iSCSI target on the local network.

    Warning: By default this commands sets up the iSCSI target with NO security.
    This is fine for testing and use in the labs, but obviously is not ideal if
    you care about the data stored on this new volume...

options:

    -n --name       the name of the new volume. This must be a valid ZFS volume name, and
                    defaults to an RFC 4122 GUID.

    -s --size       the size of the new iSCSI volume. Note that while ZFS allows you to change
                    the size of the new volume relatively easily, because the iSCSI initiator
                    sees this volume as a raw device changing the size later may be very easy or
                    very difficult depending on the initiators operating system (and the specific
                    file system being used). In other words, choose with care: by default this
                    command uses a size of 20G, which should be enough for most tasks in the
                    labs.

    -v --volume_store specifify the ZFS root of the new iSCSI volume. Defaults to "store/volumes".

Contributing to the SHU SAN Scripts

  • Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet

  • Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it

  • Fork the project

  • Start a feature/bugfix branch

  • Commit and push until you are happy with your contribution

  • Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.

  • Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

Copyright © 2011 David Love. See LICENSE.txt for further details.