Distributed Hash Tables:

The following instructions are assumed to be executed by a regular "user".

5.1 - Preliminary Notes:

• Domus ultimate goal is to provide a distributed (Cluster-based) environment for the operation of multiple Distributed Hash Tables, for distributed storage purposes. To be able to do so, the correct infrastructure must be in place, namely: i) the Domus monitorization services, which must be running in the set of cluster nodes that will be (or may be) used to support Domus clusters; ii) one or more Domus cluster (i.e., each a set of regular Domus services, supervised by a Domus supervisor service), which must be already created an active, and whose services will ultimately support one or more DHTs (note that different DHTs may be created in the same Domus cluster or in different Domus clusters).
• Once the above pre-conditions are fulfilled, the operation of DHTs may be conducted by i) the domus_manager_dht.py tool, ii) the domus_console.py tool, iii) the user-level library domus_libusr.py for development of generic client applications (in this regard, methods i) and ii) may be viewed as subcases of iii), where client applications are domus_manager_dht.py and domus_console.py). In this section, the domus_manager_dht.py tool is discussed.

5.2 - Management Tools:

Basically, the domus_manager_dht.py tool provides client applications an alternate execution path to the DHT related methods of the the user-level library domus_libusr.py. By following such path, the methods are not directly called from within the client application; instead, the client application will use OS primitives, like system, in order to execute the domus_manager_dht.py tool with proper parameters; in turn, the tool will call directly the methods of domus_libusr.py. This allows virtually any client application (weather Python-based or not) to operate Domus DHTs.
Usage:

	
[user@frontend]# domus_manager_dht.py -h
Usage: /home/domus/.domus/bin/domus_manager_dht.py -h | -H |
{ [-c cluster_conf_file_path] [-N cluster_name] [-I supervisor_interface] 
  [-P supervisor_port] [--debug] -D dht_name -o operation [more_options] }
operation: { attget | create | destroy | shutdown | restart | ping | probe | lookup | ls 
             record_put | record_get | record_del | record_probe | record_lookup }
more_options: --attset_list="attname=attvalue ... attname=attvalue"  
              --attget_name=attname --hash=hash_value -l lookup_method -k key [-d data]

Parameters:
• -h : print usage information;
• -H : print extended usage information, about DHT attributes;
• -c cluster_conf_file_path : path to the Domus cluster configuration file; for a Domus cluster named cluster_name the file is expected to be ~user/.domus/etc/domus#cluster_name#conf, but an alternate file may be given; the default is ~/.domus/etc/domus#mycluster#conf;
• -N cluster_name : the name of the Domus cluster to which belongs the DHT to be managed; the name must be unique, among the Domus clusters deployed by the same user; the default is the value of DOMUS_CLUSTER_NAME in the Domus cluster configuration file
• -I supervisor_interface : DNS name or IP address of a network interface of a cluster node selected to run the supervisor service (usually the ROCKS frontend node); the default is the value of DOMUS_SUPERVISOR_INTERFACE in the Domus cluster configuration file
• -P supervisor_port : TCP/IP port of the supervisor service; the default is the value of DOMUS_SUPERVISOR_PORT in the Domus cluster configuration file
• -D dht_name : the name of the Domus DHT to be managed; the name must be unique, among the DHTs deployed by the same user; this parameter is mandatory
• --debug : activate debug code during the management process; fully effective only if the --debug was supplied during the installation process;
• -o operation : management operation to perform; available operations (including additional parameters) are:
  • attget --attget_name=attname : returns the value of the DHT attribute named attname (feasible only for attributes that support the READ access mode - see 6.7 - dDomusUsrProxy Attributes)
  • create [-attset_list="attname=attvalue ... attname=attvalue"] : create the DHT; the creation will assume possible DHT attributes given through the parameter --attset_list (feasible only for attributes that support the WRITE access mode - see 6.7 - dDomusUsrProxy Attributes); the attribute values, all supplied in a shell-friendly string format, will be internally converted to the correct type; attributes not defined at this stage will assume default values;
  • destroy : destroy the DHT; the supervisor and regular services will eliminate all state and data records related to the DHT; the DHT does not need to be online in order to be destroyed (but its hosting Domus cluster must be active);
  • shutdown : shutdown (bring offline) the DHT: if the DHT is online, the regular services will save to disk all state and data records pertaining to the DHT (the saving is done under the directory specified by the DOMUS_SERVICE_ROOT_DIR_PATH parameter of the Domus cluster configuration file); the DHT enters the offline state, where data records are inaccessible, until the DHT is brought again to the online state;
  • restart : restart (bring online) the DHT: if the DHT is offline, the supervisor and regular services will recover the DHT state from disk and will allow dictionary operations on the DHT;
  • ping : check if the DHT is online;
  • probe : check if the DHT exists (i.e., belongs to the Domus cluster), irregardless of its current online / offline state;
  • lookup --hash=hash_value -l lookup_method : discover the routing service and the storage service responsible for the integer hash_value, using the lookup method lookup_method (this may be "direct", "cached" or "random" - see 6.10 - Lookup Methods);
  • ls : shows a recursive listing of the DHT related files in the Domus services working directory (as given by the DOMUS_SERVICE_ROOT_DIR_PATH parameter of the Domus cluster configuration file);
  • record_put -k key -d data:
    record_get -k key:
    record_del -k key: insertion, retrieval and deletion of «key,data» records indexed by key; key and data may be any string accepted by the shell; the delimiter " may need to be used to enclose the strings; note that if client applications are able to serialize key and data onto a shell-friendly format, then virtually any kind of object may be used as key and data, making a Domus DHT a generic data store;
  • record_probe -k key: check if a record indexed by key exists in the DHT (see notes above about the nature of keys)
  • record_lookup -k key -l lookup_method: discover the routing service and the storage service responsible for a putative record indexed by key (see notes above about the nature of keys) , using the lookup method lookup_method (this may be "direct", "cached" or "random" - see 6.10 - Lookup Methods);

Return/Exit Values:
A pair (val1,val2) is sent to the standard output immediately before ending execution; the pair may be captured (e.g., by a popen-like mechanism) by callers in order to know the success / failure of the operation; the generic behavior is to have val1 == 0 for success and val1 != 0 for failure; in either case val2 may be used to convey additional data or error codes, depending on the specific context (error codes are defined in the library ~domus/.domus/lib/domus_libsys.py).