From DBWiki

Contents 1 Introduction 2 Basic Hardware Configuration 3 Setting up the Storage Peers 3.1 Storage Peer Configuration File 4 Setting up the Storage Clients 4.1 Storage Client Configuration File 5 Users and Permissions 6 Automatic Start-up

Introduction

This manual will explain all of the aspects of configuring and running a live Starfish distribution in Debian and Ubuntu. You should ensure that you can run Starfish by following the Starfish QuickStart Tutorial and seeing if you can setup a basic storage network using Starfish.

Basic Hardware Configuration

It is important that all Starfish Storage Peers and Clients are on a network that propagates multicast traffic. This means that they can be on the same switch, two switches that share the same backplane, or separate switches connected via a router that routes multicast traffic between both switches.

Starfish can operate on anything ranging from a 10Mbps link to a 1Gbps link and is very resilient to transmission latencies up to 15 seconds (enough to transmit a signal around the world 30 times over).

It is recommended that you run at least RAID-5 on storage drives in a Starfish storage cloud.

Setting up the Storage Peers

Each storage peer on the network should have a unique name. Note that there is no need for IP address configuration, Starfish determines the IP addresses and ports automatically. The only pieces of information that you will need to feed to the starfishd program are:

• The name of the Peer
• The name of the Storage Network
• The directory where files and metadata should be stored

All other aspects of configuration are performed automatically.

To initialize a storage peer, you can do the following:

user@server$ mkdir megastorage-sp1
user@server$ starfishd -i -v -n sp1 -k megastorage megastorage-sp1/

Let us examine what the commands above do:

1. We created a storage directory for the starfishd program to place its files into.
2. We ran the starfishd program, which did the following
   1. -i tells starfishd to perform an initialization on the given directory.
   2. -v tells starfishd to be verbose in reporting what it is doing.
   3. -n gives a unique name to the storage peer.
   4. -k specifies the storage network that the storage peer should join.
   5. The last argument specifies the location that will store all metadata and data files.

Storage Peer Configuration File

The Debian package creates all the necessary links in the /etc/rc*.d directory to automatically start-up and shutdown the Storage Peer on boot and on shutdown. You can place a file in the /etc/starfish directory called <STORAGE_NETWORK_NAME>.conf in the following format if you want the storage peer to start up automatically on each boot:

# Bitmunk petastore Starfish daemon configuration file.

# The Starfish Storage Peer storage directory on the local file 
# system that should be used for metadata and file data
root <STARFISH_STORAGE_DIRECTORY>

# This should be uncommented if you want to perform live debugging 
# on the Starfish client using the sfdebug tool.
#debug

Setting up the Storage Clients

Each storage client on the network should have a unique name. Note that there is no need for IP address configuration, Starfish determines the IP addresses and ports automatically. The only pieces of information that you will need to feed to the mount.starfish program are:

• The name of the Peer
• The name of the Storage Network
• The directory that should be used when mounting the file system

All other aspects of configuration are performed automatically.

To mount the Starfish filesystem, you can do something along the following lines:

user@client1$ mkdir megastorage
user@client1$ mount.starfish -f -v -n sc1 -k megastorage \
              -o default_permissions,uid=`id -u`,gid=`id -g` megastorage

Let us examine what we did:

1. We started the Starfish client used to mount a POSIX-compatible filesystem under Linux.
   1. -f instructs the client to run in the foreground.
   2. -v instructs the client to be verbose in its logging.
   3. -n specifies a unique name for the Starfish client.
   4. -k specifies which storage network the Starfish client should join.
   5. -o specifies the options to use when mounting the file system. default_permissions tells the operating system to check permissions before executing certain commands. uid and gid specify the user ID and group ID to use when mounting and accessing the file system.
   6. The last option specifies which directory should be used for the mount point.

Storage Client Configuration File

The Debian package creates all the necessary links in the /etc/rc*.d directory to automatically start-up and shutdown the Storage Client on boot and on shutdown. You can place a file in the /etc/starfish directory called <STORAGE_NETWORK_NAME>.mount in the following format if you want the storage client to start up automatically on each boot:

# Bitmunk Starfish Storage Client configuration file  

# This is the unique name of the storage client
name <UNIQUE_CLIENT_NAME>

# The name of the storage cloud that should be connected to
network <STORAGE_NETWORK_NAME>

# The location of the mount point on the local file system
mountpoint <MOUNT_POINT_LOCATION>

# This should be uncommented if you want to perform live debugging 
# on the Starfish client using the sfdebug tool.
#debug

Users and Permissions

Since Starfish is a user-space filesystem, most operations will not be performed as the root user. The starfishd process (the Storage Peer) will run as the 'starfish' user.

The mount.starfish process can be run as any user that you wish. It is recommended that you use the same user that will be generating data to write to the file system, or reading data from the file system. This username should be noted in the /etc/default/starfish-client file, like so:

# Defaults file for Starfish clients

# The username that should be used when running the starfish client. 
STARFISH_USER=<UNIX_USERNAME>

Automatic Start-up

To ensure that the storage peer starts up automatically on boot, you must ensure that the following file exists:

/etc/starfish/<STORAGE_NETWORK>.conf

To ensure that the storage client starts up automatically on boot, you must ensure that the following files exist:

/etc/starfish/<STORAGE_NETWORK>.mount
/etc/default/starfish-client

To start and stop the Starfish processes, you can use the following commands:

/etc/init.d/starfishd [ start | stop ]
/etc/init.d/starfish-client [ start | stop ]