<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
[
  <!ENTITY % general-entities SYSTEM "general.ent">
  %general-entities;
]>
<book>
  <bookinfo>
    <title>Cleversafe dsNet User's Guide</title>
    <subtitle>Version &version;</subtitle>
    <copyright id="copyright">
      <year>2008</year>
      <holder>Cleversafe, Inc.</holder>
    </copyright>
  </bookinfo>
  <chapter>
    <title>Requirements</title>
    <sect1>
      <title>Software Requirements</title>
      <para>This guide provides instructions for the &version; version of the Cleversafe dsNet. 
      This and other versions of the software can be downloaded from Sourceforge at: 
      <ulink url="http://sourceforge.net/projects/cleversafe">
      http://sourceforge.net/projects/cleversafe</ulink>. These are the two packages that you
      will need to download:</para>
      <itemizedlist>
        <listitem>
          <para>dsnet-accesser-&version;.zip</para>
        </listitem>
        <listitem>
          <para>dsnet-slicestor-&version;.zip</para>
        </listitem>
      </itemizedlist>
      <para>These are the other requirements needed to run a dsNet:</para>
      <itemizedlist>
        <listitem>
          <para>Linux or an environment which supports a UNIX shell (/bin/sh)</para>
        </listitem>
        <listitem>
          <para>Sun Java JRE 1.5 or later</para>
        </listitem>
      </itemizedlist>
      <important>
        <para>Ensure that files and folders have proper permissions. Some of the command line
        applications create files which are read by other entities. This is best ensured by running
        all commands as the same user when possible. By default, some distriubutions of the DSNet
        software run the processes as user "dsnet". You should run all commands in this document as
        user dsnet if this is the case. The default ZIP distribution only requires that all
        commands are run as the same user.</para>
      </important>
    </sect1>
  </chapter>
  <chapter>
    <title>Usage</title>
    <sect1>
      <title>Setup</title>
      <sect2>
        <title>Setup the dsNet Slicestor and Accesser</title>
        <orderedlist>
          <listitem>
            <para>Unzip the dsNet Accesser zip file to the directory of your choice</para>
          </listitem>
          <listitem>
            <para>Enter the <filename>dsnet-slicestor/setup</filename> directory and run 
            <command>setup.sh</command> (You must be inside 
            <filename>/dsnet-slicestor/setup</filename>to run <command>setup.sh</command>)</para>
          </listitem>
          <listitem>
            <para>Two new files should be generated: 
            <filename>/dsnet-slicestor/conf/wrapper-server.conf</filename> and 
            <filename>/dsnet-slicestor/bin/slicestor</filename>. The default configuration has the
            server run a single server rather than a multiple server setup. 
            <filename>/dsnet-slicestor/conf/wrapper-server.conf</filename>contains a section that
            looks like this:</para>
            <screen>
    # Parameters to run a single slicestor instance per server. If multiple 
    # instances per server are desired, comment out line 4 and uncomment the 
    # (commented by default) lines 4 and 6. 
    wrapper.java.additional.1=-server
    wrapper.java.additional.2=-Dlog4j.configuration=@BASEPATH@/conf/log4j-local.xml
    wrapper.java.additional.3=-Dorg.cleversafe.xml.configuration=@BASEPATH@/conf/core-org-bindings.xml
    # Comment out this line to run multiple instances per server.
    wrapper.java.additional.4=-Dorg.cleversafe.storage.ss.xml.configuration=@BASEPATH@/conf/single-server-config.xml
    # Comment out this line to run multiple instances per server.
    #wrapper.java.additional.4=-Dorg.cleversafe.storage.ss.xml.configuration=@BASEPATH@/conf/multi-server-config.xml
    wrapper.java.additional.5=-Dorg.cleversafe.xml.properties=@BASEPATH@/conf/properties.xml
    # Comment out this line to run multiple instances per server.
    #wrapper.java.additional.6=-Dorg.cleversafe.storage.ss.daemons=8</screen>
            <para>To run an 8-wide dsnet on the same machine for testing purposes, follow the
            instructions as provided in the comments section.</para>
          </listitem>
          <listitem>
            <para>By default, the 
            <command>/dsnet-slicestor/bin/slicestor</command> script has a section titled
            RUN_AS_USER. Change the username in this file to be any user which has read and write
            access to the 
            <filename>/dsnet-slicestor</filename>folder. To run as the current user (as in the user
            which is logged in when the slicestor script is run), simply leave the line commented
            out.</para>
            <screen>    RUN_AS_USER="dsnet"</screen>
            <para>Run 
            <command>/dsnet-slicestor/bin/slicestor start</command>. Slicestor, unlike 
            <command>setup.sh</command>, can be run from anywhere on the local system (paths are 
            made un-relative as part of the setup process). The server should now be running. Also 
            note that the previous steps only need be executed once per install.</para>
          </listitem>
          <listitem>
            <para>Run 
            <command>/dsnet-accesser/setup/setup.sh</command>. As with the slicestor, you must be
            inside 
            <filename>/dsnet-accesser/setup</filename> to run <command>setup.sh</command>.</para>
          </listitem>
          <listitem>
            <para>Start the accesser daemon: <command>dsnet-accesser/bin/accesser start</command></para>
          </listitem>
          <listitem>
            <para>Run 
            <command>/dsnet-accesser/bin/dsnet-create-vault</command>: 
            <command>dsnet-accesser/bin/dsnet-create-vault --name="vault-name"
            --descriptor="../conf/descriptor.xml"</command></para>
          </listitem>
          <listitem>
            <para>Now that the vault has been created, a new target needs to be created on the
            iSCSI portal with the 
            <command>dsnet-create-target</command> command:</para>
            <screen>dsnet-accesser/bin/dsnet-create-target --name="vault"
            --iqn="this-is-the-iqn"</screen>
          </listitem>
        </orderedlist>
        <para>At this point, the accesser should be started and ready for an initiator to
        connect.</para>
      </sect2>
    </sect1>
    <sect1>
      <title>Optional commands</title>
      <para>A number of optional commands are available.</para>
      <itemizedlist>
        <listitem>
          <para>
          <command>dsnet-list-vaults</command>: Connects to the accesser daemon and lists all
          created vaults.</para>
        </listitem>
        <listitem>
          <para>
          <command>dsnet-list-targets</command>: Connects to the accesser daemon and lists all
          created iSCSI targets.</para>
        </listitem>
        <listitem>
          <para>
          <command>dsnet-delete-target</command>: Connects to the accesser daemon and deletes an
          iSCSI target.</para>
        </listitem>
        <listitem>
          <para>
          <command>dsnet-delete-vault</command>: Connects to the accesser daemon and deletes a
          created vault (note that any targets using this vault must be deleted first).</para>
        </listitem>
        <listitem>
          <para>
          <command>dsnet-change-portal</command>: Change iSCSI portal.</para>
        </listitem>
      </itemizedlist>
      <para>For more information on these optional commands, please refer to the command line help
      interfaces provided when these commands are executed.</para>
    </sect1>
    <sect1>
      <title>Stopping Accesser and Slicestor</title>
      <para>The scripts in the bin directory of both the accesser and slicestor distributions
      (after running 
      <command>setup.sh</command>) act like scripts that would normally be inserted into 
      <filename>/etc/init.d</filename>.
      You can issue start, stop, or status commands to them.</para>
      <para>Note that there is an issue where if the install path of the accesser or slicestor is
      long, the stop commands will not work. A workaround is pending.</para>
    </sect1>
  </chapter>
  <chapter>
    <title>Uninstall</title>
      <para>Since the Accesser and Slicestor are self-contained in one directory (including all
      configuration and data), simply delete the installation directory.</para>
  </chapter>
  <chapter>
    <title>Using the Accesser's iSCSI Target Functionality</title>
    <sect1>
      <title>Log on to the iSCSI Target</title>
        <para>You can use the <ulink url="http://www.open-iscsi.org/">Open-iSCSI Project's</ulink>
        <command>iscsiadm</command> program to log in to the target by 
        typing:</para>
        <screen>    iscsiadm --mode node --targetname [target-name] --portal [portal] --login</screen>
        <para><filename>[target-name]</filename> refers to the IQN name of the target. 
        <filename>[portal]</filename> refers to the iSCSI Target host address and port like 
        '127.0.0.1:3260'. If only a host address is specified the port defaults to 3260.</para>
        <para>You can find the targets advertising on a particular IP address by issuing the 
        command:</para>
        <screen>    iscsiadm -m discovery -t sendtargets -p [portal]</screen>
        <para>Where <filename>[portal]</filename> is the portal name of the target which is composed 
        of an IP address and a port in the form IP:port.</para>
        <para>To log out of the target you need to type a command similar to the one for logging in 
        except tat you need to replace the <command>--login</command> option with 
        <command>--logout</command>.</para>
    </sect1>
    <sect1>
      <title>Partitioning the Device</title>
        <para>Use a partition manipulation program like fdisk or parted to partition the device 
        created then the initiator logs into the target. This device  could be something like 
        <filename>/dev/sdb</filename> or <filename>/dev/hdb</filename> depending on your environment.  
        With <command>fdisk</command>, you would type <command>fdisk /dev/sdb</command> and follow 
        the interactive instructions to partition a device like <filename>/dev/sdb</filename>. 
        Instructions to use <command>fdisk</command> can be found on its man page.</para>
        <para>You can find the particular device created when you logged in the iSCSI initiator to 
        the target by typing the following command:</para>
        <screen>    iscsiadm -m session -i</screen>
        <para>The device name will appear under the 'Attached SCSI devices' section.</para>
    </sect1>
    <sect1>
      <title>Creating an filesystem on the disk partition(s)</title>
        <para>Use a filesystem creation tool like <command>mke2fs</command> to create an ext2 or 
        ext3 filesystem on the partition created above, for example, by typing 
        <command>mke2fs /dev/sdb1</command> where <filename>/dev/sdb1</filename> is the partition 
        created after the previous step to create an ext2 partition.</para>
    </sect1>
    <sect1>
      <title>Mounting the filesystem</title>
        <para>Use the <command>mount</command> command to mount a mount point to the filesystem 
        created above: <command>mount /dev/sdb1 [mount-point]</command>', where [mount-point] is a 
        mount point of your choice.  Unmount your partition with <command>umount</command>.</para>
    </sect1>
    <sect1>
      <title>Using the Grid</title>
        <para>You can use the mounted filesystem as you would any other, for example by copying 
        files to it with <command>cp</command>, removing them with <command>rm</command>, etc.
        </para>
    </sect1>
  </chapter>
</book>
