= SHU SAN Scripts

Together these scripts define a +store+ command, used to simplify the
task of creating 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:

      help                 Show help for a command
      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

Copyright (c) 2011 David Love. See LICENSE.txt for
further details.