Storage Appliance API v3.1.x

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  Receiving Complex Data Types

Low-level C functions do not support retrieving complex data types directly. In that case DBus functions should be used. The following example in C prints a dictionary of string arrays returned by an SA-API method; this type of dictionary is denoted in this document as dictionary {string => array of (string)}

	msg = nms_execute (proxy, "get_luns",
			DBUS_TYPE_STRING, &volume_name,
			DBUS_TYPE_INVALID);
	printf ("\nLUNS list: \n");

	if (msg) {
		int current_type;
		struct DBusMessageIter iter, subiter, item;
		char *path, *val;
		int arg_type = dbus_message_iter_get_arg_type (msg->reply);
		int elem_type = dbus_message_iter_get_element_type (msg->reply);
		if(arg_type != DBUS_TYPE_ARRAY || elem_type != DBUS_TYPE_DICT_ENTRY)
		{
			printf("Returned value is not a dictionary\n");
			return;
		}

		// enter the dictionary
		dbus_message_iter_recurse (msg->reply, &iter);

		while ((current_type = dbus_message_iter_get_arg_type (&iter)) != DBUS_TYPE_INVALID)
		{
			int args = 0;

			// enter the dictionary item
			dbus_message_iter_recurse (&iter, &subiter);

			// iterate through dictionary items
			while((current_type = dbus_message_iter_get_arg_type (&subiter)) != DBUS_TYPE_INVALID)
			{
				if(current_type == DBUS_TYPE_STRING)
				{
					// dictionary key is found (string type)
					dbus_message_iter_get_basic (&subiter, &path);
					args++;
					printf("%d. %s\n", args, path);
				}
				//if(current_type == DBUS_TYPE_DICT_ENTRY)
				if(current_type == DBUS_TYPE_ARRAY)
				{
					// dictionary value is found (array of string type)
					// enter the array
					dbus_message_iter_recurse (&subiter, &item);
					// iterate through all strings in array
					while((current_type = dbus_message_iter_get_arg_type (&item)) != DBUS_TYPE_INVALID)
					{
						if(current_type == DBUS_TYPE_STRING)
						{
							dbus_message_iter_get_basic (&item, &val);
							dbus_message_iter_next (&item);
						}
						printf("    %s\n", val?val:"");
					}
				}
				dbus_message_iter_next (&subiter);

			}
			dbus_message_iter_next (&iter);
		}
	}

5.5  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.6  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  Groups of Appliances Management

SA-API Interface Object

Properties

Inherited Methods

6.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

No return values

Usage Examples

3.  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

6.2  com.nexenta.nms.ApplGroup::get_all

(array of (dictionary {string => string}))  get_all (string pattern)

Returns array of all supported groups of all types

Parameters

Return Value

6.3  com.nexenta.nms.ApplGroup::get_all_members

(array of (string))  get_all_members (void)

Get the list of all members in all groups

No parameters

Return Value

6.4  com.nexenta.nms.ApplGroup::get_group_types

(array of (string))  get_group_types (void)

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

No parameters

Return Value

See Also

6.5  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

3.  get_members('storage_1') 

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

See Also

7  General Appliance Management

SA-API Interface Object

Properties

Inherited Methods

7.1  com.nexenta.nms.Appliance::add_swap

(void)  add_swap (string zname)

Add zvol as an additional swap area

Parameters

No return values

See Also

7.2  com.nexenta.nms.Appliance::configure_ugen_device

(void)  configure_ugen_device (dictionary {string => dictionary {string => string}} device_info)

Configuring generic USB device

Parameters

No return values

7.3  com.nexenta.nms.Appliance::create_checkpoint

(string)  create_checkpoint (string snapname)

Create checkpoint from specified system snapshot

Parameters

Return Value

7.4  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

7.5  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.

No parameters

Return Value

See Also

7.6  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

No return values

See Also

7.7  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

No return values

See Also

7.8  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

No return values

See Also

7.9  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.

No parameters

Return Value

See Also

7.10  com.nexenta.nms.Appliance::dbus_auth_keys_remove

(void)  dbus_auth_keys_remove (string key)

Remove authentication key.

Parameters

No return values

See Also

7.11  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

No return values

See Also

7.12  com.nexenta.nms.Appliance::get_cpu_info

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

Get detailed per-CPU information

No parameters

Return Value

Usage Examples

3.  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' } }

7.13  com.nexenta.nms.Appliance::get_etchosts_rec

(array of (string))  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 (while API uses file '/etc/inet/hosts', the symlink '/etc/hosts' is present for BSD compatibility) - 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

3.  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

7.14  com.nexenta.nms.Appliance::get_fqdn

(string)  get_fqdn (void)

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

No parameters

Return Value

Usage Examples

3.  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'.

7.15  com.nexenta.nms.Appliance::get_general_diagnostics

(string)  get_general_diagnostics (int32 level, bool call_is_local)

Get general diagnostics

Parameters

Return Value

7.16  com.nexenta.nms.Appliance::get_host_by_addr

(string)  get_host_by_addr (string ipaddr)

Get hostname by IP address

Parameters

Return Value

7.17  com.nexenta.nms.Appliance::get_kbd_layouts

(array of (string))  get_kbd_layouts (void)

Get all supported keyboard layouts

No parameters

Return Value

Usage Examples

3.  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)

7.18  com.nexenta.nms.Appliance::get_license_info

(dictionary {string => string})  get_license_info (void)

Get license information

No parameters

Return Value

Usage Examples

3.  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

7.19  com.nexenta.nms.Appliance::get_memstat

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

Get RAM utilization information

No parameters

Return Value

Usage Examples

3.  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 }

7.20  com.nexenta.nms.Appliance::get_saved_configurations

(array of (string))  get_saved_configurations (void)

Get the list of all available saved configurations.

No parameters

Return Value

Usage Examples

3.  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

7.21  com.nexenta.nms.Appliance::get_serial_names

(dictionary {string => string})  get_serial_names (void)

Get the list of names of all available serial ports

No parameters

Return Value

7.22  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

3.  get_subtimezones("America", "Mexico") 

get time zones for Mexico.

See Also

7.23  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

3.  get_timezone_continent("Europe/Prague") 

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

See Also

7.24  com.nexenta.nms.Appliance::get_timezone_continents

(array of (string))  get_timezone_continents (void)

Get all time zone continents

No parameters

Return Value

Usage Examples

3.  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

7.25  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

3.  get_timezone_country_code("Brazil") 

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

See Also

7.26  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

3.  get_timezones("Australia") 

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

See Also

7.27  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)

No parameters

Return Value

Usage Examples

3.  get_uptime() 

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

7.28  com.nexenta.nms.Appliance::group_configuration_sync_set

(void)  group_configuration_sync_set (bool enable)

Synchronize group configuration by enabling or disabling

Parameters

No return values

7.29  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.

No parameters

Return Value

See Also

7.30  com.nexenta.nms.Appliance::list_conf_ugen_hid_devs

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

Get configuration of all USB devices

No parameters

Return Value

7.31  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

7.32  com.nexenta.nms.Appliance::list_unconf_hid_devs

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

Get list of unconfigured USB devices

No parameters

Return Value

7.33  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

3.  ns_getent('group', '', '') 

get all groups including those listed in the LDAP directory

6.  ns_getent('group', 'local', '') 

retrieve only local groups

9.  ns_getent('passwd', 'local', '') 

get all local users

12.  ns_getent('passwd', 'ldap', 'jo') 

get LDAP users with usernames starting with 'jo'

See Also

7.34  com.nexenta.nms.Appliance::ns_group_del

(void)  ns_group_del (string group)

Delete the specified group

Parameters

No return values

Usage Examples

3.  ns_user_del('contractors') 

delete group 'contractors'

See Also

7.35  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

3.  ns_group_exists('staff') 

check if the group 'staff' is defined

See Also

7.36  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

3.  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

7.37  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

3.  ns_group_idmap_get('staff') 

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

See Also

7.38  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

No return values

Usage Examples

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

define local group 'staff'

See Also

7.39  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

3.  ns_netgroup('netgroup-engineering') 

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

See Also

7.40  com.nexenta.nms.Appliance::ns_user_del

(void)  ns_user_del (string user, bool del_home_folder)

Delete the specified user

Parameters

No return values

Usage Examples

3.  ns_user_del('john', 1) 

delete user 'john' and destroy the associated home folder

See Also

7.41  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

3.  ns_user_exists('john') 

check if the user 'john' is defined

See Also

7.42  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

3.  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

7.43  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

3.  ns_user_idmap_get('john') 

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

See Also

7.44  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

No return values

Usage Examples

3.  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

7.45  com.nexenta.nms.Appliance::ping_tcp

(bool)  ping_tcp (string host, int32 timeout, int32 port)

Ping host via TCP

Parameters

Return Value

7.46  com.nexenta.nms.Appliance::poweroff

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

Get descriptions of the saved appliance's configurations

Parameters

No return values

See Also

7.47  com.nexenta.nms.Appliance::reboot

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

Reboot the appliance

Parameters

No return values

See Also

7.48  com.nexenta.nms.Appliance::reset_ugen_configuration

(void)  reset_ugen_configuration (void)

Reset the current USB devices configuration

No parameters

No return values

7.49  com.nexenta.nms.Appliance::restore_configuration

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

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

3.  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

7.50  com.nexenta.nms.Appliance::restore_volume_services

(bool)  restore_volume_services (string volume_name)

Restore volume services

Parameters

Return Value

7.51  com.nexenta.nms.Appliance::save_configuration

(string)  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

7.52  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 (while API uses file '/etc/inet/hosts', the symlink '/etc/hosts' is present for BSD compatibility) - 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

No return values

Usage Examples

3.  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

7.53  com.nexenta.nms.Appliance::set_license_key

(bool)  set_license_key (string new_license_key)

Update license key

Parameters

Return Value

Usage Examples

3.  set_license_key('EVAL-E501340681-5D2UD6-BIAHJK') 

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

See Also

7.54  com.nexenta.nms.Appliance::ssh_bind

(int32)  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

7.55  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

3.  ssh_check_binding('root', 'remote-host.domain') 

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

6.  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

7.56  com.nexenta.nms.Appliance::ssh_list_bindings

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

Get all existing SSH bound hosts

No parameters

Return Value

See Also

7.57  com.nexenta.nms.Appliance::ssh_unbind

(int32)  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

7.58  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

7.59  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

7.60  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

7.61  com.nexenta.nms.Appliance::ssl_list_bindings

(dictionary {string => string})  ssl_list_bindings (void)

Get trusted host information for all existing certificates

No parameters

Return Value

See Also

7.62  com.nexenta.nms.Appliance::ssl_list_certificates

(array of (string))  ssl_list_certificates (void)

Get certificate files

No parameters

Return Value

See Also

7.63  com.nexenta.nms.Appliance::ssl_list_certinfos

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

Get certificate information for all existing certificates

No parameters

Return Value

See Also

7.64  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

7.65  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

7.66  com.nexenta.nms.Appliance::stat_file

(dictionary {string => string})  stat_file (string filepath)

Collects and returns info for file path, including file type, perms, size, inode, gid, uid, timestamps and so on

Parameters

Return Value

7.67  com.nexenta.nms.Appliance::sysnotice_check

(string)  sysnotice_check (void)

Check NMS sytem notice file

No parameters

Return Value

7.68  com.nexenta.nms.Appliance::sysnotice_set

(void)  sysnotice_set (string notice_msg)

Update NMS sytem notice file

Parameters

No return values

7.69  com.nexenta.nms.Appliance::sysnotice_unset

(void)  sysnotice_unset (void)

Clear NMS sytem notice file

No parameters

No return values

7.70  com.nexenta.nms.Appliance::upgradable_packages

(array of (string))  upgradable_packages (void)

Get the list of packages which will be upgraded

No parameters

Return Value

7.71  com.nexenta.nms.Appliance::upgradable_packages_check

(array of (string))  upgradable_packages_check (array of (string) packages_for_check)

Determine what packages require upgrade

Parameters

Return Value

7.72  com.nexenta.nms.Appliance::upgrade_check

(int32)  upgrade_check (int32 invalidate)

Check for appliance software upgrades

Parameters

Return Value

Usage Examples

3.  upgrade_check(0) 

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

8  Appliance Backup

SA-API Interface Object

Properties

Inherited Methods

8.1  com.nexenta.nms.ApplianceBackup::get_saved_configurations

(array of (dictionary {string => string}))  get_saved_configurations (string dir, bool short)

Returns a list of existing saved appliance configurations

Parameters

Return Value

8.2  com.nexenta.nms.ApplianceBackup::get_state

(string)  get_state (void)

Returns current state of a save/restore process

No parameters

Return Value

8.3  com.nexenta.nms.ApplianceBackup::restore_app_configuration

(int32, array of (string))  restore_app_configuration (array of (string) component_list, dictionary {string => string} params)

Restores appliance configuration

Parameters

Return Value

8.4  com.nexenta.nms.ApplianceBackup::save_app_configuration

(string)  save_app_configuration (array of (string) component_list, dictionary {string => string} params)

Save appliance configuration

Parameters

Return Value

9  Statistic Collection

SA-API Interface Object

Properties

Inherited Methods

10  Virtual Container

SA-API Interface Object

No properties

No inherited methods

10.1  com.nexenta.nms.Container::destroy

(void)  destroy (string child_name, string not set)

Destroy child object specified by its name

Parameters

No return values

10.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

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

get the size of 'c2t0d0'

6.  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

10.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

3.  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.

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

get all 'c2t0d0' disk properties

9.  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 }

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

get all 'vol1/a' folder properties

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

get all 'vol1' volume properties

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

get all 'vol1/a@today' snapshot properties

21.  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

10.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

3.  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' )

6.  network_interfaces_if->get_names('') 

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

9.  volume_if->get_names('') 

get all volumes

12.  zvol_if->get_names('') 

get all zvols

15.  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

10.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

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

get names of all CD-ROMs in the appliance

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

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

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

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

See Also

10.6  com.nexenta.nms.Container::object_exists

(bool)  object_exists (string child_name)

Verify that object exists

Parameters

Return Value

Usage Examples

3.  lun_if->object_exists('c0d0') 

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

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

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

See Also

10.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

No return values

Usage Examples

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

enable compression on the folder 'vol1/a'

See Also