Storage Appliance API

Copyright (C) Nexenta Systems, Inc. All rights reserved.

1  API Overview

Welcome to the NexentaStor Storage Appliance API (SA-API) Reference documentation. This API reference provides comprehensive information allowing to build new and extend existing management services, management clients and applications on top of NexentaStor.

Storage Appliance API (SA-API) uses RPC-like D-Bus protocol that employes TCP/IP transport. D-Bus is a powerful and flexible inter-process communication (IPC) mechanism that allows: for the service providers - to register the provided services, and for the clients - to lookup on the network and use the provided services in a location-independent way. NexentaStor leverages D-Bus to provide universal and comprehensive API to manage and monitor all aspects of the appliance's operation. For more information on dbus visit the D-Bus Project Homepage. There are many good introductions and tutorials available on the web, including for instance this D-Bus Tutorial.

Since SA-API provides a higher level abstraction on top of D-Bus, knowledge of these materials is, however, not a prerequisite. SA-API makes it easy to create new, or modify existing applications in C or C++, Perl, Python or Ruby. More language specific SA-API extensions may be added in the future. Still, for reference purposes the corresponding sources are listed below:

The API provides access to the appliance's management objects and services. The appliance's management object hierarchy includes: lun, volume, folder, snapshot, network, network interface, network service, storage service, indexer, zvol, statistic collector, fault trigger, reporter, and others. Each object implements and publishes a part of the API, which makes the latter a by-product of two interrelated but still distinctly separate driving "forces": the appliance's object taxonomy and the required functionality of the 2nd tier NAS.

All client management applications use SA-API to monitor and administer the appliance. This ensures consistent view of the appliance from all clients, transactional behavior of all management administrative and monitoring operations, and easy third-party integrations.

The currently existing management clients include: management console (NMC) and web GUI (Nexenta Management View a.k.a. NMV), fault triggers and storage services, statistic collectors and daily/weekly reporters. All of them execute management operations first by acquiring an object proxy, and second, by calling one of the object's APIs. The SA-API supports many-to-many operation, in the sense that it allows to communicate to multiple statically bound or dynamically discovered appliances on the Internet/Intranet, and at the same time supports multi-user access to any given appliance.

SA-API has bindings for C, C++, Perl, Python and Ruby. This documentation contains examples and samples to demonstrate SA-API in these languages.

The prerequisites to using SA-API include:

• General knowledge of one or more of the following programming languages: C, C++, Perl, Python or Ruby
• User-level experience with the NexentaStor appliance

The API can be used to take the full advantage of the NexentaStor capabilities, which include unlimited including unlimited incremental backups or 'snapshots', snapshot mirroring (replication), block level mirroring ('CDP'), integrated search, and the inherent virtualization, performance, thin provisioning and more. The following block diagram shows Nexenta Management Server - the sole provider of the API - and some of its clients.

2  Block Diagram

3  Terms and Conventions

4  Object Model

NexentaStor management object model is designed to provision, manage, monitor, and control the life-cycle of all components that comprise the appliance, including network and data services, volumes (pools) and folders (filesystems), snapshots and zvols (virtual block devices), LUNs (physical and virtual disks), and more. The management architecture is in basic ways similar to CORBA and Java RMI, whereby object proxies on the client side are used to represent remote (implementation) objects, on a remote appliance.

The following lists all SA-API proxy objects - interface objects representing appliance's objects and services. The table comprises the following information:

• In the first column, proxy interface name as seen by the client application after executing nms_client_init() - a helper method to initialize SA-API client. The former is provided with the language specific bindings as part of the NexentaStor SDK.
• Next is D-Bus name of the SA-API interface (proxy) object. This name is often referred to as D-Bus "path" because it looks like a filesystem path. For instance, NexentaStor appliance interface object is named '/Root/Appliance'.
• In the 3rd column, a link to the section in this document containing part of the API that can be exercised via the corresponding SA-API interface.
• Finally, in the last column, an immediate parent in the interface inheritance hierarchy. In many cases this is Virtual Container, which also means that, for instance, com.nexenta.nms.Container::get_child_props is available via the corresponding (child) interface objects. The fact that, for instance, Snapshot Management Interface is derived from Virtual Container indicates that the Snapshot Management Interface effectively "contains" all concrete snapshots, and can be used to perform the subset of SA-API operations on the snapshots defined by this Interface.

NexentaStor SDK comes with a number of local (client-side) helpers. This includes nms_client_init() - to initialize SA-API client, and nms_remote_obj() - to acquire SA-API interface proxy object associated with a given appliance (identified by its hostname or IP address). Both nms_client_init() and nms_remote_obj() are provided with the language-specific bindings and demonstrated in the Section Examples and Usage Cases below.

All SA-API interface objects without exception are extensions of SA-API generic Virtual Object. Thus, all methods provided by the Virtual Object are polymorphically available via SA-API interface objects listed in the table above. For instance, appliance->get_props() returns appliance's properties, as per com.nexenta.nms.Object::get_props specification.

Majority of the listed SA-API interface objects extend Virtual Container interface. SA-API Container is an abstraction to aggregate multiple objects of the same type: snapshots, volumes, folders, network services, network interfaces, runners, LUNs (disks), storage services. A typical sequence of steps to execute an operation on a specific (contained) object instance includes:

• acquiring all or some (filtered) object names, via com.nexenta.nms.Container::get_names
• invoking SA-API method, with the unique name of the "contained" object's as the first parameter.

SA-API Virtual Container abstraction is repeatedly demonstrated throughout this reference; for specific examples in C, Perl, Python and Ruby please refer to Section Examples and Usage Cases below.

5  Data Types

SA-API "data type" is either a primitive data type or a complex type built based on the primitive data types, similar to abstract data types in Java and struct data types in C and C++. SA-API data types are used to define arguments and return values in the SA-API methods listed in this reference documentation. The primitive data types include:

The complex data types are:

Rest of this section demonstrates usage of these SA-API data types in different languages.

5.1  Primitive Data Types

As far as Perl, Python and Ruby, SA-API primitive types are in fact the corresponding programming language's primitive types: no translation necessary. The next table shows a correspondence between D-Bus and C/C++ data types:

PRIMITIVE DATA TYPE	C/C++ TYPE
string	DBUS_TYPE_STRING
int32	DBUS_TYPE_INT32
bool	DBUS_TYPE_BOOLEAN

None of the primitive data types require any special preparation for using it as an argument in the SA-API method call: it is enough to declare a C variable using one of the listed DBUS_TYPE_??? primitives, and then pass a pointer to it in an SA-API method call.

Processing SA-API results is also easy. The following example prints a string  returned by an SA-API call

	char *str;
	if (nms_get_basic (msg, DBUS_TYPE_STRING, &str))
		printf ("Received = %s\n", str);
		else printf ("Error getting string  value");

5.2  Receiving an Array

The following example in C prints an array type returned by an SA-API method; this type of array is denoted in this document as array of (string)

	char **array;
	int count, i;
	count = nms_get_basic (msg, DBUS_TYPE_CHAR_ARRAY, &array);
	for (i = 0; i < count; i++){
		printf ("item = %s\n", array[i]);
	};

This snippet of Perl code simply prints a returned array of strings denoted in this document as array of (string). Note that SA-API complex data type array  is a regular Perl array, while SA-API dictionary  is simply a Perl hash.

	for my $item (@$array) {
		print "item=$item\n";
	}

5.3  Receiving a Dictionary

The following example in C prints a dictionary type returned by an SA-API method; this type of dictionary is denoted in this document as dictionary {string => string}

	char **dict;
	int count, i;
	count = nms_get_basic (msg, DBUS_TYPE_CHAR_DICT, &dict);
	for (i = 0; i < count; i++){
		printf ("%s => %s\n", dict[i * 2], dict[i * 2 + 1]);
	};

Next is a Perl code sample that does the same: prints a returned dictionary {string => string}. Note that complex data types are always returned by reference.

	for my $key (keys %$dict) {
		print "key=$key, value=$dict->{$key}\n";
	}

5.4  Passing an Array

The following example in C prepares an array of strings denoted in this document as array of (string), to further be passed as a parameter in an SA-API method call:

	char *array[] = {
		"a", "b", "c", "d"
		};

This single-line Perl code fills an array of strings, to be passed as a parameter in SA-API method invocation:

	my @array = ('a', 'b', 'c', 'd');

5.5  Passing a Dictionary

The following example in C prepares a dictionary {string => string}, to further be passed as a parameter in an SA-API method call:

	char *dict[] = {
		"name", "appliance", 
		"version", "1.0",
		"release_date", "06/17/2008"
		};

Next is a Perl example that fills in the same type of a dictionary {string => array of (string)}, to be transferred to the remote appliance for execution, for instance in a call to modify user's ACL:

	my %dict = (
		allow => ['read_data', 'read_acl'],
		deny => ['write_data']
	);

6  Virtual Base Object

Properties

6.1  com.nexenta.nms.Object::get_prop

string  get_prop (string propname)

Get property value

Parameters

Return Value

Usage Examples

1.  appliance_if->get_prop('nms_version') 

Get NMS version for the NMS that runs on a given appliance. This assumes that appliance_if is interface object that represents the corresponding appliance

2.  server_if->get_prop('trace_level') 

Get NMS trace level. This assumes that server_if represents NMS server interface object

See Also

6.2  com.nexenta.nms.Object::get_props

dictionary {string => string}  get_props (string pattern)

Get { propname => value } dictionary of all properties matching the specified pattern

Parameters

Return Value

Usage Examples

1.  appliance_if->get_props('^n') 

Assuming appliance_if is the corresponding interface object, return all appliance's properties the names of which start with the letter 'n'. This list may look as follows: { 'name' => 'Appliance', 'nms_version' => '1.1' }

See Also

6.3  com.nexenta.nms.Object::set_prop

void  set_prop (string propname, string value)

Set property value

Parameters

Return Value

Usage Examples

1.  server_if->set_prop('trace_level', '10') 

Assuming server_if represents NMS server interface object, this will set its tracing level to 10

See Also

7  Virtual Container

Properties

7.1  com.nexenta.nms.Container::destroy

void  destroy (string child_name)

Destroy child object specified by its name

Parameters

Return Value

See Also

7.2  com.nexenta.nms.Container::get_child_prop

string  get_child_prop (string child_name, string propname)

For a given (contained) child, get the specified property

Parameters

Return Value

Usage Examples

1.  lun_if->get_child_prop('c2t0d0', 'size') 

Get the size of 'c2t0d0'

2.  network_interfaces_if->get_child_prop('e1000g0', 'info') 

Get information on the 'e1000g0' interface. This assumes that the network_interfaces_if represents the corresponding container object (that contains all network interfaces on a given appliance).

See Also

7.3  com.nexenta.nms.Container::get_child_props

dictionary {string => string}  get_child_props (string child_name, string pattern)

For a given (contained) child get { propname => value } dictionary of all properties matching the specified pattern

Parameters

Return Value

Usage Examples

1.  plugin('nms-autocdp')->get_child_props('tier2', '') 

Ask nms-autocdp plugin interface object for all properties of the existing auto-cdp 'tier2' instance that the former contains. This, and the following examples, assume that the container interface (nms-autocdp plugin in this case) is already retrieved (as described elsewhere), and represents the corresponding container on a given appliance.

2.  lun_if->get_child_props('c2t0d0', '') 

Get all 'c2t0d0' disk properties

3.  lun_if->get_child_props('c2t0d0', 'size') 

Get properties that match 'size' substring for the 'c2t0d0'. Following is an example of returned dictionary: { 'size' => '4.1GB', 'size_bytes' => 4294967296 }

4.  folder_if->get_child_props('vol1/a', '') 

Get all 'vol1/a' folder properties

5.  volume_if->get_child_props('vol1', '') 

Get all 'vol1' volume properties

6.  snapshot_if->get_child_props('vol1/a@today', '') 

Get all 'vol1/a@today' snapshot properties

7.  folder_if->get_child_props('vol1/a', 'mount') 

Get all mount-related properties of the folder 'vol1/a'. The returned dictionary may look as follows: { 'mounted' => 'yes', 'canmount' => 'on', 'mountpoint' => '/volumes/vol1/a' }.

See Also

7.4  com.nexenta.nms.Container::get_names

array of (string)  get_names (string pattern)

Get array of all (contained) children names matching the specified pattern

Parameters

Return Value

Usage Examples

1.  folder_if->get_names('^vol1/a/') 

Recursively get all sub-folders of the folder 'vol1/a'. The returned array ma look like: ( 'vol1/a/b', 'vol1/a/c', 'vol1/a/b/ddd' )

2.  network_interfaces_if->get_names('') 

Get all existing network interfaces. An example of return: ( 'e1000g0', 'e1000g1', 'e1000g2' )

3.  volume_if->get_names('') 

Get all volumes

4.  zvol_if->get_names('') 

Get all zvols

5.  snapshot_if->get_names('^vol1\/a[\/\@]') 

Recursively get all snapshots of the folder 'vol1/a' and its sub-folders. An example of returned array: ( 'vol1/a@yesterday', 'vol1/a@today', 'vol1/a/b@yesterday' )

See Also

7.5  com.nexenta.nms.Container::get_names_by_prop

array of (string)  get_names_by_prop (string propname, string propval_pattern, string childname_pattern)

Get array of all (container) children which has matching property value, for the names matching the 2nd specified pattern. The method effectively does the following: select all children where child name matches and property matches . As always, an empty pattern value means that the pattern is ignored.

Parameters

Return Value

Usage Examples

1.  lun_if->get_names_by_prop('type', 'cdrom', '') 

Get names of all CD-ROMs in the appliance

2.  runner_if->get_names_by_prop('type', 'collector', '') 

Get all collectors. The resulting returned array may look like: ( 'network-collector', 'nfs-collector', 'volume-collector' )

3.  runner_if->get_names_by_prop('type', 'collector', '^v') 

Get a subset of all collectors with the names starting with 'v'

See Also

7.6  com.nexenta.nms.Container::object_exists

bool  object_exists (string child_name)

Verify that object exists

Parameters

Return Value

Usage Examples

1.  lun_if->object_exists('c0d0') 

Returns non-zero if the appliance has 'c0d0' disk

2.  folder_if->object_exists('vol1/a') 

Returns non-zero if the folder 'vol1/a' exists

See Also

7.7  com.nexenta.nms.Container::set_child_prop

void  set_child_prop (string child_name, string propname, string propvalue)

For a given (contained) child update the specified property with a new value

Parameters

Return Value

Usage Examples

1.  folder_if->set_child_prop('vol1/a', 'compression', 'on') 

Enable compression on the folder 'vol1/a'

2.  zvol_if->set_child_prop('vol1/zvol1', 'shareiscsi', 'on') 

Share zvol 'vol1/zvol1' via iSCSI

See Also

7.8  com.nexenta.nms.Container::trylock

bool  trylock (string child_name, int32 lock_type)

Make an attempt to lock the specified child

Parameters

Return Value

Usage Examples

1.  folder_if->trylock('vol1/a', 1) 

Lock folder 'vol1/a' for reading. Note that multiple read locks may co-exist simultaneously

2.  folder_if->trylock('vol1/a', 2) 

Exclusively lock folder 'vol1/a' and its sub-folders.

See Also

7.9  com.nexenta.nms.Container::unlock

void  unlock (string child_name, int32 lock_type)

Unlock the specified child

Parameters

Return Value

Usage Examples

1.  folder_if->unlock('vol1/a', 1) 

Remove read lock from the folder 'vol1/a'

2.  folder_if->unlock('vol1/a', 2) 

Remove write (exclusive) lock from the folder 'vol1/a'

See Also

8  General Appliance Management

SA-API Interface Object

Properties

Inherited Methods

8.1  com.nexenta.nms.Appliance::add_swap

void  add_swap (string zname)

Add zvol as an additional swap area

Parameters

Return Value

See Also

8.2  com.nexenta.nms.Appliance::dbus_auth_iptable_is_set

bool  dbus_auth_iptable_is_set (string action, string mask_ip)

Determine whether the specified deny or allow access rule is present in the appliance's iptable.

Parameters

Return Value

See Also

8.3  com.nexenta.nms.Appliance::dbus_auth_iptable_list

dictionary {string => string}  dbus_auth_iptable_list (void)

Get all iptable access rules. Background: The appliance provides secure access to other Storage Appliances, as well as administrative management client applications on the network. The inter-appliance access is executed either via SSH, or via SA-API (User Guide, Section "Storage Appliance API"), or both. All management client applications, whether developed internally by Nexenta Systems, Inc and/or by 3rd parties, access appliance via SA-API. In all cases, access to an appliance requires client authentication. SA-API supports two authentication mechanisms: 1) via IP address of the client machine, and 2) via ssh-keygen generated authentication keys. The 2nd, ssh-keygen based, mechanism is the preferred one. This (2nd) mechanism is realized via APIs: com.nexenta.nms.Appliance::dbus_auth_keys_add, com.nexenta.nms.Appliance::dbus_auth_keys_remove, com.nexenta.nms.Appliance::dbus_auth_keys_list. This is the mechanism used by Storage Appliances to communicate between themselves. The latter is required to run storage replication services, to execute in a group mode, to switch between appliances for the purposes of centralized management. Once the appliances are ssh-bound, all SA-API interfaces become available, and get executed in a secure way. Please see User Guide Sections "Centralized Management" and "Secure Access" for more information.

Parameters

Return Value

See Also

8.4  com.nexenta.nms.Appliance::dbus_auth_iptable_set

void  dbus_auth_iptable_set (string action, string mask_ip)

Deny or allow access to the appliance from the specified IP address or subnet. This API results in adding another matching rule to the appliance's iptable. Background: The appliance provides secure access to other Storage Appliances, as well as administrative management client applications on the network. The inter-appliance access is executed either via SSH, or via SA-API (User Guide, Section "Storage Appliance API"), or both. All management client applications, whether developed internally by Nexenta Systems, Inc and/or by 3rd parties, access appliance via SA-API. In all cases, access to an appliance requires client authentication. SA-API supports two authentication mechanisms: 1) via IP address of the client machine, and 2) via ssh-keygen generated authentication keys

Parameters

Return Value

See Also

8.5  com.nexenta.nms.Appliance::dbus_auth_iptable_unset

void  dbus_auth_iptable_unset (string action, string mask_ip)

Remove deny or allow access rule from the appliance's iptable. This is to reverse effect of com.nexenta.nms.Appliance::dbus_auth_iptable_set.

Parameters

Return Value

See Also

8.6  com.nexenta.nms.Appliance::dbus_auth_keys_add

void  dbus_auth_keys_add (string key, string value)

Add new key to the client key authorization table. Background: The appliance provides secure access to other Storage Appliances, as well as administrative management client applications on the network. The inter-appliance access is executed either via SSH, or via SA-API (User Guide, Section "Storage Appliance API"), or both. All management client applications, whether developed internally by Nexenta Systems, Inc and/or by 3rd parties, access appliance via SA-API. In all cases, access to an appliance requires client authentication. SA-API supports two authentication mechanisms: 1) via IP address of the client machine, and 2) via ssh-keygen generated authentication keys. The 2nd, ssh-keygen based, mechanism is the preferred one. This (2nd) mechanism is realized via APIs: com.nexenta.nms.Appliance::dbus_auth_keys_add, com.nexenta.nms.Appliance::dbus_auth_keys_remove, com.nexenta.nms.Appliance::dbus_auth_keys_list. This is the mechanism used by Storage Appliances to communicate between themselves. The latter is required to run storage replication services, to execute in a group mode, to switch between appliances for the purposes of centralized management. Once the appliances are ssh-bound, all SA-API interfaces become available, and get executed in a secure way. Please see User Guide Sections "Centralized Management" and "Secure Access" for more information.

Parameters

Return Value

See Also

8.7  com.nexenta.nms.Appliance::dbus_auth_keys_list

dictionary {string => string}  dbus_auth_keys_list (void)

Get all authorization keys and their IDs. Background: The appliance provides secure access to other Storage Appliances, as well as administrative management client applications on the network. The inter-appliance access is executed either via SSH, or via SA-API (User Guide, Section "Storage Appliance API"), or both. All management client applications, whether developed internally by Nexenta Systems, Inc and/or by 3rd parties, access appliance via SA-API. In all cases, access to an appliance requires client authentication. SA-API supports two authentication mechanisms: 1) via IP address of the client machine, and 2) via ssh-keygen generated authentication keys. The 2nd, ssh-keygen based, mechanism is the preferred one. This (2nd) mechanism is realized via APIs: com.nexenta.nms.Appliance::dbus_auth_keys_add, com.nexenta.nms.Appliance::dbus_auth_keys_remove, com.nexenta.nms.Appliance::dbus_auth_keys_list. This is the mechanism used by Storage Appliances to communicate between themselves. The latter is required to run storage replication services, to execute in a group mode, to switch between appliances for the purposes of centralized management. Once the appliances are ssh-bound, all SA-API interfaces become available, and get executed in a secure way. Please see User Guide Sections "Centralized Management" and "Secure Access" for more information.

Parameters

Return Value

See Also

8.8  com.nexenta.nms.Appliance::dbus_auth_keys_remove

void  dbus_auth_keys_remove (string key)

Remove authentication key.

Parameters

Return Value

See Also

8.9  com.nexenta.nms.Appliance::delete_swap

void  delete_swap (string zname)

Remove zvol swap area - undo the effect of com.nexenta.nms.Appliance::add_swap

Parameters

Return Value

See Also

8.10  com.nexenta.nms.Appliance::get_cpu_info

dictionary {int32 => dictionary {string => string}}  get_cpu_info (void)

Get detailed per-CPU information

Parameters

Return Value

Usage Examples

1.  appliance_if->get_cpu_info() 

Get detailed per-CPU information. A sample output follows: { '0' => { 'clock_MHz' => '2300', 'crtime' => '15.99439196', 'cpu_type' => 'i386', 'core_id' => '0', 'model' => '15', 'ncore_per_chip' => '1', 'brand' => 'Intel(r) Core(tm)2 Duo CPU T7700 @ 2.40GHz', 'state' => 'on-line', 'clog_id' => '0', 'implementation' => 'x86 (GenuineIntel 6F8 family 6 model 15 step 8 clock 2300 MHz)', 'fpu_type' => 'i387 compatible', 'state_begin' => '1213042644', 'stepping' => '8', 'supported_frequencies_Hz' => '2299926901', 'vendor_id' => 'GenuineIntel', 'pkg_core_id' => '0', 'current_clock_Hz' => '2299926901', 'ncpu_per_chip' => '1', 'chip_id' => '0', 'class' => 'misc', 'snaptime' => '54922.184402079', 'family' => '6' } }

8.11  com.nexenta.nms.Appliance::get_etchosts_rec

void  get_etchosts_rec (string pattern)

Given a hostname or a part of a hostname, or FQDN - get the corresponding record from the appliance's local host table. In modern systems host tables have been superseded by DNS. However, the host table is still widely used for small sites isolated from the network. The local host table may also be required by some of the appliance's services, in particular replication and HA cluster services. Please see the corresponding manual pages for details. In addition, if in your environment the local information rarely changes, and the network is not connected to the Internet, DNS offers little advantage. The host table (file '/etc/hosts') - is a simple text file that associates IP addresses with hostnames, one line per IP address. For each host a single line should be present with the following information: IP_address hostname [aliases...]. This API simply retrieves the corresponding record, and presents the result as array of strings, for instance: ('192.168.102.194', 'chost', 'chost.cdomain')

Parameters

Return Value

Usage Examples

1.  appliance_if->get_etchosts_rec('chost') 

Get 'chost' record from the apliance's local host table. The result may look like: ('192.168.102.194', 'chost', 'chost.cdomain')

See Also

8.12  com.nexenta.nms.Appliance::get_fqdn

string  get_fqdn (void)

Get a fully qualified domain name (FQDN) of the appliance.

Parameters

Return Value

Usage Examples

1.  appliance_if->get_fqdn() 

Get appliance's FQDN. For example, assuming appliance's local hostname 'myhost' and domain name is 'example.com', the fully qualified domain name would be 'myhost.example.com'.

8.13  com.nexenta.nms.Appliance::get_kbd_layouts

array of (string)  get_kbd_layouts (void)

Get all supported keyboard layouts

Parameters

Return Value

Usage Examples

1.  appliance_if->get_kbd_layouts() 

Get all available keyboard layouts. This may return the following array: (Albanian Belarusian Belgian Bulgarian Croatian Czech Danish Dutch Finnish French French-Canadian Hungarian German Greek Icelandic Italian Japanese-type6 Japanese Korean Latin-American Lithuanian Latvian Macedonian Malta_UK Malta_US Norwegian Polish Portuguese Russian Serbia-And-Montenegro Slovenian Slovakian Spanish Swedish Swiss-French Swiss-German Taiwan)

8.14  com.nexenta.nms.Appliance::get_license_info

dictionary {string => string}  get_license_info (void)

Get license information

Parameters

Return Value

Usage Examples

1.  appliance_if->get_license_info() 

Get license information. A sample return follows: { 'license_key' => 'EVAL-E501340681-5D2UD6-BIAHJK', 'license_cntr_used' => '-1', 'license_type' => 'EVAL', 'license_message' => 'Software license verified OK', 'license_days_left' => '-1', 'license_size_left_percent' => '65', 'license_size_used' => '3.2TB', 'license_cntr_max' => '-1', 'machine_sig' => '5D2UD6' }

See Also

8.15  com.nexenta.nms.Appliance::get_memstat

dictionary {string => int32}  get_memstat (void)

Get RAM utilization information

Parameters

Return Value

Usage Examples

1.  appliance_if->get_memstat() 

Get RAM information. A sample output follows: { 'ram_total' => 511, 'ram_unusable' => 8, 'ram_kernel' => 326, 'ram_locked' => 0, 'ram_free' => 51, 'ram_paging' => 0, 'ram_used' => 125 }

8.16  com.nexenta.nms.Appliance::get_saved_configurations

array of (string)  get_saved_configurations (void)

Get the list of all available saved configurations.

Parameters

Return Value

Usage Examples

1.  appliance_if->get_saved_configurations() 

Retrieve all available saved configuration filenames and descriptions. The result may look like: ( '1252099979.tar.gz', 'Fri Sep 4 14:32:59 2009', '', '1252100931.tar.gz', 'Fri Sep 4 14:48:51 2009', 'auto-tier destroyed', '1252101756.tar.gz', 'Fri Sep 4 15:02:36 2009', 'hostname changed'). Please note that the result in this example contains 3 triples, each describing a particular saved configuration.

See Also

8.17  com.nexenta.nms.Appliance::get_subtimezones

array of (string)  get_subtimezones (string continent, string country)

Get time zones for the specified country located in the specified continent

Parameters

Return Value

Usage Examples

1.  appliance_if->get_subtimezones("America", "Mexico") 

Get time zones for Mexico.

See Also

8.18  com.nexenta.nms.Appliance::get_timezone_continent

string  get_timezone_continent (string timezone)

Get time zone code for the specified country

Parameters

Return Value

Usage Examples

1.  appliance_if->get_timezone_continent("Europe/Prague") 

Translate time zone => continent. The result: "Europe".

See Also

8.19  com.nexenta.nms.Appliance::get_timezone_continents

array of (string)  get_timezone_continents (void)

Get all time zone continents

Parameters

Return Value

Usage Examples

1.  appliance_if->get_timezone_continents() 

Get names of all time zone continents. The result will be: (Africa America Antarctica Arctic Asia Atlantic Australia Europe Pacific Indian)

See Also

8.20  com.nexenta.nms.Appliance::get_timezone_country_code

string  get_timezone_country_code (string country)

Get time zone code for the specified country

Parameters

Return Value

Usage Examples

1.  appliance_if->get_timezone_country_code("Brazil") 

Get time zone code for Brazil. The result: "BR".

See Also

8.21  com.nexenta.nms.Appliance::get_timezones

array of (string)  get_timezones (string continent)

Given a time zone continent, get all its time zones

Parameters

Return Value

Usage Examples

1.  appliance_if->get_timezones("Australia") 

Get all time zones for Australia. The result: array that has a single entry: ("Australia").

See Also

8.22  com.nexenta.nms.Appliance::get_uptime

dictionary {string => double}  get_uptime (void)

Get appliance's uptime, including the following information: The current time, how long the system has been running, how many users are currently logged on, and the system load averages for the past 1, 5, and 15 minutes. The times are measured in seconds from the start of epoch (00:00:00 UTC Jan 1st, 1970)

Parameters

Return Value

Usage Examples

1.  appliance_if->get_uptime() 

Get appliance's uptime information. A sample output: { 'boot' => '86400', 'time' => '1213163656', 'load1' => '0.03', 'load5' => '0.03', 'load15' => '0.02' }

8.23  com.nexenta.nms.Appliance::list_appliances

dictionary {string => string}  list_appliances (void)

Get all SSH-bound as well as dynamically discovered on a local subnet appliances that are currently online. The returned dictionary includes those and only those appliances that are currently online from the perspective of the appliance that executes the operation.

Parameters

Return Value

See Also

8.24  com.nexenta.nms.Appliance::list_swap

array of (string)  list_swap (bool include_hdr_total)

Get summary information about total swap space usage, existing swap areas, and availability

Parameters

Return Value

See Also

8.25  com.nexenta.nms.Appliance::ns_getent

array of (string)  ns_getent (string entity, string type, string filter)

Get local and LDAP based users, groups, and netgroups

Parameters

Return Value

Usage Examples

1.  appliance_if->ns_getent('group', '', '') 

Get all groups including those listed in the LDAP directory

2.  appliance_if->ns_getent('group', 'local', '') 

Retrieve only local groups

3.  appliance_if->ns_getent('passwd', 'local', '') 

Get all local users

4.  appliance_if->ns_getent('passwd', 'ldap', 'jo') 

Get LDAP users with usernames starting with 'jo'

See Also

8.26  com.nexenta.nms.Appliance::ns_group_del

void  ns_group_del (string group)

Delete the specified group

Parameters

Return Value

Usage Examples

1.  ns_user_del('contractors') 

Delete group 'contractors'

See Also

8.27  com.nexenta.nms.Appliance::ns_group_exists

string  ns_group_exists (string group)

Find out whether a given group exists; if found, the method returns group type

Parameters

Return Value

Usage Examples

1.  appliance_if->ns_group_exists('staff') 

Check if the group 'staff' is defined

See Also

8.28  com.nexenta.nms.Appliance::ns_group_get

dictionary {string => string}  ns_group_get (string group)

Given a local or LDAP defined group, get properties such as group ID, group members, group type ('local' or 'ldap'). LDAP defined groups may have other properties.

Parameters

Return Value

Usage Examples

1.  appliance_if->ns_group_get('staff') 

Get properties and members of the group 'staff'. Following is a sample result: { 'type' => 'local', 'gidNumber' => 3001, 'memberUid' => 'john mike alice' }

See Also

8.29  com.nexenta.nms.Appliance::ns_group_idmap_get

string  ns_group_idmap_get (string group)

Get identity mapping for a given Unix group.

Parameters

Return Value

Usage Examples

1.  appliance_if->ns_group_idmap_get('staff') 

Get idmap for group 'staff'. The result may look like: 'wingroup:Staff@corp.com -> unixgroup:staff'

See Also

8.30  com.nexenta.nms.Appliance::ns_group_set

void  ns_group_set (string group, string type, dictionary {string => string} props)

Modify existing local group or create a new group, if does not exist. The new/existing group properties include: 'gidNumber' (group ID) and 'memberUid' that specifies a space delimited list of group members. The current implementation will work only for locally defined (type = 'local') groups

Parameters

Return Value

Usage Examples

1.  appliance_if->ns_group_set('staff', 'local', { 'memberUid' => "john mike alice" }) 

Define local group 'staff'

See Also

8.31  com.nexenta.nms.Appliance::ns_netgroup

array of (string)  ns_netgroup (string netgroup)

Get a list of hosts (computers) included in a given netgroup

Parameters

Return Value

Usage Examples

1.  appliance_if->ns_netgroup('netgroup-engineering') 

List all hosts from netgroup 'netgroup-engineering'. The result may look like: ('host1.mycorp.com', 'host2.mycorp.com', ...)

See Also

8.32  com.nexenta.nms.Appliance::ns_user_del

void  ns_user_del (string user, bool del_home_folder)

Delete the specified user

Parameters

Return Value

Usage Examples

1.  appliance_if->ns_user_del('john', 1) 

Delete user 'john' and destroy the associated home folder

See Also

8.33  com.nexenta.nms.Appliance::ns_user_exists

string  ns_user_exists (string user)

Find out whether a given user exists; if found, the method returns user type

Parameters

Return Value

Usage Examples

1.  appliance_if->ns_user_exists('john') 

Check if the user 'john' is defined

See Also

8.34  com.nexenta.nms.Appliance::ns_user_get

dictionary {string => string}  ns_user_get (string user)

Given a local or LDAP defined user, get properties such as user ID (UID), home folder on the appliance, group ID, etc.

Parameters

Return Value

Usage Examples

1.  appliance_if->ns_user_get('smb') 

Return properties for user 'smb'; a sample return follows: { 'user' => 'smb', 'type' => 'local', 'gidNumber' => 1, 'group' => 'other', 'uidNumber' => 1001, 'homeFolder' => '', 'description' => '' }

See Also

8.35  com.nexenta.nms.Appliance::ns_user_idmap_get

string  ns_user_idmap_get (string user)

Get identity mapping for a given Unix user.

Parameters

Return Value

Usage Examples

1.  appliance_if->ns_user_idmap_get('john') 

Get idmap for user 'john'. The result may look like: 'winuser:John@corp.com -> unixuser:john'

See Also

8.36  com.nexenta.nms.Appliance::ns_user_set

void  ns_user_set (string user, string type, dictionary {string => string} props)

Modify existing local user or add new local user, if the user does not exist. The user properties include: 'uidNumber' (the user's ID), 'gidNumber' (the user's default group ID), 'homeFolder', 'description'. The current implementation will work only for locally defined (type = 'local') users

Parameters

Return Value

Usage Examples

1.  appliance_if->ns_user_set('new_user_x', 'local', { 'uidNumber' => 1020, 'gidNumber' => 75, 'description' => "new description" }) 

Assuming 'new_user_x' does not exist, this will create a new local user definition with the default group ID = 75, etc.

See Also

8.37  com.nexenta.nms.Appliance::poweroff

void  poweroff (bool force, bool reconfigure, string extra_options)

Power off the appliance

Parameters

Return Value

See Also

8.38  com.nexenta.nms.Appliance::reboot

void  reboot (bool force, bool reconfigure, string extra_options)

Reboot the appliance

Parameters

Return Value

See Also

8.39  com.nexenta.nms.Appliance::restore_configuration

array of (string)  restore_configuration (string component, bool overwrite_newer, bool check_only)

Restore appliance's configuration from the most recent copy stored at a pre-defined location. The current location in use is defined by NMS property 'saved_configroot'. The operation restores service definitions for the appliance's storage services to the point in time they (the definitions) were saved via com.nexenta.nms.Appliance::save_configuration

Parameters

Return Value

Usage Examples

1.  appliance_if->restore_configuration('auto-sync', 0, 0) 

Restore the latest saved auto-sync configuration; do not override existing newer auto-sync service(s), if any

See Also

8.40  com.nexenta.nms.Appliance::save_configuration

void  save_configuration (string description)

Save appliance's configuration at a pre-defined location. The current location in use is defined by NMS property 'saved_configroot'. The saved configuration will include service definitions for the appliance's storage services. The saved configuration includes the following components: basic | mailer | nms | nmc | auto-snap | auto-scrub | auto-sync | auto-tier, where 'basic' configuration includes appliance basic settings: hostname, domainname, etc., 'mailer' - SMTP server, username, password, etc., 'nms' - NMS configuration options, 'nmc' - NMC configuration options. The rest component types stand for service definitions of the corresponsing automated (auto-) services. Note that com.nexenta.nms.Appliance::restore_configuration method can be used to later restore only some components of the saved configuration, and not necessarily the entire configuration.

Parameters

Return Value

See Also

8.41  com.nexenta.nms.Appliance::set_etchosts_rec

void  set_etchosts_rec (string ipaddr, array of (string) hostnames)

Add, replace or delete a record from the appliance's local host table. The local host table is first searched by ipaddr (the first argument). If the rest arguments is an empty array, the corresponding located record is removed. Otherwise, if the record is located, it is modified, and alternatively - added. Background: In modern systems host tables have been superseded by DNS. However, the host table is still widely used for small sites isolated from the network. The local host table may also be required by some of the appliance's services, in particular replication and HA cluster services. Please see the corresponding manual pages for details. In addition, if in your environment the local information rarely changes, and the network is not connected to the Internet, DNS offers little advantage. The host table (file '/etc/hosts') - is a simple text file that associates IP addresses with hostnames, one line per IP address. For each host a single line should be present with the following information: IP_address hostname [aliases...].

Parameters

Return Value

Usage Examples

1.  appliance_if->set_etchosts_rec('192.168.102.194', ('chost', 'chost.cdomain')) 

Add a record to resolve hostname to IP address to the apliance's local host table, or - if the record already exists - replace it with the specified information.

See Also

8.42  com.nexenta.nms.Appliance::set_license_key

bool  set_license_key (string new_license_key)

Update license key

Parameters

Return Value

Usage Examples

1.  appliance_if->set_license_key('EVAL-E501340681-5D2UD6-BIAHJK') 

Update appliance's license key with a new (license key) value

See Also

8.43  com.nexenta.nms.Appliance::ssh_bind

void  ssh_bind (string user, string hostport, string password)

SSH-bind a given (user, appliance) to the specified remote host. Two appliances are considered SSH-bound if ssh_bind operation is successfully performed for (and by) 'root'.

Parameters

Return Value

See Also

8.44  com.nexenta.nms.Appliance::ssh_check_binding

bool  ssh_check_binding (string user, string hostport)

Check whether the specified appliance's user is SSH-bound to the specified remote host. Two appliances are considered SSH-bound if ssh_check_binding returns true for user 'root'.

Parameters

Return Value

Usage Examples

1.  appliance_if->ssh_check_binding('root', 'remote-host.domain') 

Check whether the appliance is SSH-bound to 'remote-host.domain'.

2.  appliance_if->ssh_check_binding('mike', '192.168.17.145:4000') 

Check whether the user 'mike' is SSH-bound to host with IP address 192.168.17.145 via the explicitly specified port 4000.

See Also

8.45  com.nexenta.nms.Appliance::ssh_list_bindings

dictionary {string => array of (string)}  ssh_list_bindings (void)

Get all existing SSH bound hosts

Parameters

Return Value

See Also

8.46  com.nexenta.nms.Appliance::ssh_unbind

void  ssh_unbind (string user, string hostport, bool force)

SSH-unbind a given (user, appliance) from the specified remote host. Two appliances are considered SSH-bound if ssh_bind operation is successfully performed for (and by) 'root'. This operation reverses the effect of com.nexenta.nms.Appliance::ssh_bind

Parameters

Return Value

See Also

8.47  com.nexenta.nms.Appliance::ssl_bind

int32  ssl_bind (string certificate, string cname)

Add a new certificate to LDAP managed database

Parameters

Return Value

See Also

8.48  com.nexenta.nms.Appliance::ssl_check_binding

bool  ssl_check_binding (string cname)

Check whether the specified certificate exists in database

Parameters

Return Value

See Also

8.49  com.nexenta.nms.Appliance::ssl_direct_bind

int32  ssl_direct_bind (string hostport, string cname)

Add a new certificate to LDAP managed database

Parameters

Return Value

See Also

8.50  com.nexenta.nms.Appliance::ssl_list_bindings

dictionary {string => string}  ssl_list_bindings (void)

Get trusted host information for all existing certificates

Parameters

Return Value

See Also

8.51  com.nexenta.nms.Appliance::ssl_list_certificates

array of (string)  ssl_list_certificates (void)

Get certificate files

Parameters

Return Value

See Also

8.52  com.nexenta.nms.Appliance::ssl_list_certinfos

array of (dictionary {string => string})  ssl_list_certinfos (void)

Get certificate information for all existing certificates

Parameters

Return Value

See Also

8.53  com.nexenta.nms.Appliance::ssl_unbind

int32  ssl_unbind (string cname)

Remove the specified certificate from database - compare with com.nexenta.nms.Appliance::ssl_unbind_by_hostname

Parameters

Return Value

See Also

8.54  com.nexenta.nms.Appliance::ssl_unbind_by_hostname

int32  ssl_unbind_by_hostname (string host_fqdn)

Remove certificate from the LDAP managed database

Parameters

Return Value

See Also

8.55  com.nexenta.nms.Appliance::upgrade_check

int32  upgrade_check (bool invalidate)

Check for appliance software upgrades

Parameters

Return Value

Usage Examples

1.  appliance_if->upgrade_check(0) 

Check for upgrades; use the latest cached result of the automatically performed check for upgrades.

9  Groups of Appliances Management

SA-API Interface Object

Properties

Inherited Methods

9.1  com.nexenta.nms.ApplGroup::create

void  create (string group_name, dictionary {string => string} group_desc, array of (string) group_members)

Create a new group of two or more appliances. To form a group, make sure there is network connectivity to remote appliances, and/or run com.nexenta.nms.Appliance::ssh_bind to create new ssh-binding(s).

Parameters

Return Value

Usage Examples

1.  applgroup_if->create('storage_1', {'description' => 'storage 1 group'}, ('thost.mycorp.com', 'zhost.mycorp.com')) 

Group the two specified appliances ina group, and name this group 'storage_1'

See Also

9.2  com.nexenta.nms.ApplGroup::destroy

void  destroy (string group_name, bool)

Destroy the specified group of appliances. This is an opposite of com.nexenta.nms.ApplGroup::create, to remove the definition of the specified group.

Parameters

Return Value

See Also

9.3  com.nexenta.nms.ApplGroup::get_group_types

void  get_group_types (void)

Returns array of supported group types, for instance ['basic']

Parameters

Return Value

See Also

9.4  com.nexenta.nms.ApplGroup::get_members

array of (string)  get_members (string group_name)

For a given group, get its member appliances

Parameters

Return Value

Usage Examples

1.  applgroup_if->get_members('storage_1') 

Get members of the group 'storage_1'. The result may look like: ('thost.mycorp.com', 'zhost.mycorp.com')

See Also

10  Virtual Runner

SA-API Interface Object

Properties

Inherited Methods

10.1  com.nexenta.nms.Runner::disable

void  disable (string runner_name)

Disable the specified runner, ie stop (suspend) its execution. The runner must be registered (see com.nexenta.nms.Runner::register); otherwise this interface method will through an exception.

Parameters

Return Value

Usage Examples

1.  enable('volume-collector') 

Disable 'volume-collector'

See Also

10.2  com.nexenta.nms.Runner::enable

void  enable (string runner_name)

Enable the specified runner. The runner must be registered (see com.nexenta.nms.Runner::register); otherwise this interface method will through an exception. If the runner was disabled (see com.nexenta.nms.Runner::disable), this operation effectively results in the runner resuming its execution.

Parameters

Return Value

Usage Examples

1.  runner_if->enable('runners-check') 

Enable 'runners-check'

See Also

10.3  com.nexenta.nms.Runner::execute

void  execute (string runner_name)

Execute the specified runner. The operation allows to run the runner on-demand, without waiting for its scheduled execution time. The runner must be registered (see com.nexenta.nms.Runner::register); otherwise this interface method will through an exception. Note that the runner may not necessarily be enabled; it is allowed to execute a disabled (suspended) runner.

Parameters

Return Value

Usage Examples

1.  runner_if->execute('services-check') 

Execute 'services-check'

See Also

10.4  com.nexenta.nms.Runner::get_tunables

dictionary {string => string}  get_tunables (string runner_name, string pattern, bool exclude_description)

Get the runner's tunables and their descriptions. For defintion of the term "runner", see Terms and Conventions. For the list of concrete "runners" that inherit Virtual Runner, please refer to Section Object Model

Parameters

Return Value

Usage Examples

1.  runner_if->get_tunables('memory-check', '', 0) 

Retrieve all 'memory-check' tunables and their descriptions. The result will include the following: { 'free_swap_critical' => '10', 'paging_critical_shortdesc' => 'Critically high paging intensity threshold (percentage)', 'paging_critical' => '10', 'paging_critical_longdesc' => 'Alarm (severity=critical) is raised if the intensity of paging to disk (scan rate) gets beyond this critical threshold', 'num_procs' => '5', 'free_ram_notice_shortdesc' => 'Free memory low threshold (percentage of total RAM)', 'max_rss_suspect_shortdesc' => 'Maximum resident set size (RSS) of any process in the system (megabytes)', 'enable_swap_check' => '1', ... }

2.  runner_if->get_tunables('memory-check', 'free', 1) 

Get 'memory-check' tunables that contain 'free' in their names, and do not retrieve their descriptions. The result follows: { 'free_swap_critical' => '10', 'free_ram_notice' => '5', 'free_swap_notice' => '25' }

See Also

10.5  com.nexenta.nms.Runner::is_registered

bool  is_registered (string runner_name)

Check whether the specified runner is registered with the appliance. For defintion of the term "runner", see Terms and Conventions.

Parameters

Return Value

Usage Examples

1.  runner_if->is_registered('services-check') 

Find out whether the 'services-check' fault trigger is registered

See Also

10.6  com.nexenta.nms.Runner::register

void  register (string runner_name, dictionary {string => string} params, dictionary {string => string} tunables)

Register the specified runner. The operation validates runner's parameters and registers the runner in the appliance's database. The runner will not execute until it is registered. For defintion of the term "runner", see Terms and Conventions. For the list of concrete "runners" that inherit Virtual Runner, please refer to Section Object Model

Parameters

Return Value

Usage Examples

1.  runner_if->register('network-util-weekly', { 'type' => 'reporter', 'description' => "Weekly networking report", 'freq_type' => 'weekly', 'freq_day' => 6, 'freq_hour' => 2, 'freq_period' => 1}, {} ) 

Register weekly reporter to execute every Saturday at 2am

See Also

10.7  com.nexenta.nms.Runner::set_tunable

void  set_tunable (string runner_name, string propname, string propval)

Modify the runner's (tunable) property value. A given runner may have two types of properties: standard properties with well-known names (for instance, 'type', 'description'), and tunables. The latter are runner-specific and can have any names. Use the generic com.nexenta.nms.Container::set_child_prop - to modify the standard runner's properties, and com.nexenta.nms.Runner::set_tunable - to modify the tunables

Parameters

Return Value

Usage Examples

1.  runner_if->set_tunable('memory-check', 'paging_critical', 5) 

Modify the 'memory-check' tunable called 'paging_critical'. The operation in this case would set a new threshold for the paging intensity. To view all runner's tunables and their descriptions, use com.nexenta.nms.Runner::get_tunables

See Also

10.8  com.nexenta.nms.Runner::unregister

void  unregister (string runner_name)

Unregister the specified runner. The operation reverses the effect of com.nexenta.nms.Runner::register - it destroys the active runner instance and remove the corresponding record from the registration database. Note that, once unregistered, the runner cannot be enabled; to simply stop the runner from executing, use com.nexenta.nms.Runner::disable

Parameters