Storage Appliance API v40-1-0

263 Pages·2014·1.17 MB·English

Storage Appliance API v40-1-0
Copyright (C) Nexenta Systems, Inc. All rights reserved.
1 API Overview
2 Block Diagram
3 Terms and Conventions
4 Object Model
5 Data Types
5.1 Primitive Data Types
5.2 Receiving an Array
5.3 Receiving a Dictionary
5.4 Receiving Complex Data Types
5.5 Passing an Array
5.6 Passing a Dictionary
6 Virtual Base Object
6.1 get_prop - Get the property value
6.2 get_props - Get { propname => value } dictionary of all properties ...
6.3 set_prop - Set the value of property
6.4 set_props - Set the properties according to dictionary
6.5 trylock_self - Make an attempt to lock the object. Unlike com.nexenta.nms.Container::trylock ...
6.6 unlock_self - Unlock object. Unlike com.nexenta.nms.Container::unlock it unlocks object self, not ...
7 Virtual Container
7.1 destroy - Destroy a child object.
7.2 get_child_prop - Get the value of a property for a child object. ...
7.3 get_child_props - Get the list of properties and values that match the ...
7.4 get_names - Get the list of names of all child objects that ...
7.5 get_names_by_prop - Get the list of all child objects that have a ...
7.6 object_exists - Verify that an object exists.
7.7 set_child_prop - Update a property of a child object with a new ...
7.8 trylock - Try to lock a child object.
7.9 unlock - Unlock a child object.
8 Appliance Backup
8.1 get_saved_configurations - Returns the list of saved appliance configurations
8.2 get_state - Returns current state of a save/restore process
8.3 restore_app_configuration - Restores appliance configuration
8.4 save_app_configuration - Save appliance configuration
9 AutoScrub (volume scrubbing) Service
10 AutoSnap (snapshot) Service
11 AutoTier (data replication) Service
12 Fault Management
12.1 clear - Clear specific fault ID
12.2 clear_all - Clear all faults generated by the specified fault trigger ...
12.3 event - Create and send an event for the specified trigger ...
12.4 fault - Generate a fault notification
12.5 get_faults - Get the list of faults generated by the specified fault ...
13 Folder (Filesystem)
13.1 add_group_acl - Add the group's permissions to access a given folder and ...
13.2 add_user_acl - Add the user's permissions to access a given folder and ...
13.3 clone - Create a clone of a snapshot. Clone is a writable ...
13.4 create - Create "paths" to folders
13.5 create_snapshot - Snapshot a given folder and possibly its sub-folders
13.6 create_with_props - Create a "path" of folders. This API method enables you ...
13.7 del_group_acl - Remove the group's permissions from the folder's ACL
13.8 del_user_acl - Remove the user's permissions from the folder's ACL
13.9 get_acl - Get folder's ACL for the entities that match the pattern ...
13.10 get_acl_by_index - Retrieve the complete folder's ACL, and possibly check for duplicate ...
13.11 get_aclinfo - Get the ACL related static information: the groups of permissions ...
13.12 get_all_names - Get an array of all child object names that match ...
13.13 get_groupspace - Get the groupspace parameters
13.14 get_groupspace_types - Get the list of available groupspace types.
13.15 get_prop_valid_values - Get the valid range and/or enumeration for a given folder's ...
13.16 get_subfolder_names - Get the sub-folder names
13.17 get_userspace - Get the userspace parameters
13.18 get_userspace_types - Get the available userspace types
13.19 get_version_info - Get the folder's ZFS version
13.20 has_zfs_prop - Determine whether a zfs property exists or not
13.21 inherit_prop - Restore a system-default inheritance of a ZFS property. The method ...
13.22 promote - Promotes a cloned dataset to no longer be dependent on ...
13.23 reset_acl - Reset the folder's ACLs to the system default (POSIX, built-in) ...
13.24 set_group_acl - Set the group's permissions to access a given folder and ...
13.25 set_group_owner - Change the group ownership for a given folder.
13.26 set_user_acl - Set the user's permissions to access a given folder and ...
13.27 set_user_owner - Change the user ownership of a folder
13.28 upgrade - Upgrade folder's ZFS version
13.29 upgrade_folders - Upgrade folder's ZFS version recursively
14 Folder and Snapshot Indexing Facility (Search Engine)
14.1 create - Create indexer for the specified folder. Once created, the indexer ...
14.2 search - Search the folder and its snapshot(s).
15 General Appliance Management
15.1 add_swap - Add a zvol as an additional swap area.
15.2 configure_ugen_device - Configure a generic USB device.
15.3 create_checkpoint - Create a checkpoint from a system snapshot.
15.4 dbus_auth_iptable_is_set - Determine whether the deny/allow access rule is present in the ...
15.5 dbus_auth_iptable_list - Get all iptable access rules. The NexentaStor appliance provides a ...
15.6 dbus_auth_iptable_set - Deny/Allow access to the NexentaStor appliance from the specified IP ...
15.7 dbus_auth_iptable_unset - Remove Deny/Allow access rule from the appliance's iptable. This method ...
15.8 dbus_auth_keys_add - Add a new key to the key authorization table on ...
15.9 dbus_auth_keys_list - Get all authorization keys and their IDs. NexentaStor Storage Appliance ...
15.10 dbus_auth_keys_remove - Remove an authentication key.
15.11 delete_swap - Remove zvol swap area, and undo the result of the ...
15.12 get_cpu_info - Get the detailed per-CPU information.
15.13 get_dumpdir - Get the location of the
15.14 get_etchosts_rec - Get the record from the appliance's local host table for ...
15.15 get_fqdn - Get a fully qualified domain name (FQDN) of the appliance. ...
15.16 get_general_diagnostics - Get the general diagnostics, collect all log information in a ...
15.17 get_host_by_addr - Resolve a hostname by IP address.
15.18 get_kbd_layouts - Get the list of all supported keyboard layouts.
15.19 get_license_info_ - Get the license information.
15.20 get_memstat - Get the RAM utilization information.
15.21 get_saved_configurations - Get the list of all saved configurations.
15.22 get_saved_user_configurations - Returns the list of saved appliance configurations. This method is ...
15.23 get_serial_names - Get the list of all available serial ports.
15.24 get_subtimezones - Get the list of time zones for the specified country ...
15.25 get_timezone_continent - Get the time zone code for the specified time zone. ...
15.26 get_timezone_continents - Get the list of continents for the available time zones. ...
15.27 get_timezone_country_code - Get the time zone code for the specified country. ...
15.28 get_timezones - Get the list of all available time zones for the ...
15.29 get_upgrade_info - Get the information about upgrades on this NexentaStor appliance ...
15.30 get_uptime - Get the appliance's uptime, including the following information: the current ...
15.31 group_configuration_sync_set - Synchronize group configuration by enabling or disabling the synchronization. ...
15.32 is_rebooting - Verify that NexentaStor appliance is rebooting
15.33 list_appliances - Get the list of all SSH-bound as well as dynamically ...
15.34 list_conf_ugen_hid_devs - Get the configuration of all USB devices.
15.35 list_swap - Get the summary information about total swap space usage, existing ...
15.36 list_unconf_hid_devs - Get the list of unconfigured USB devices.
15.37 ns_getent - Get the list of local and LDAP users, groups, and ...
15.38 ns_group_del - Delete a group
15.39 ns_group_exists - Verify that a group exists.
15.40 ns_group_get - Get the group properties, such as group ID, group members, ...
15.41 ns_group_idmap_get - Get the identity mapping for a Unix group.
15.42 ns_group_set - Modify the existing local group or create a new group. ...
15.43 ns_netgroup - Get the list of hosts (computers) included in a netgroup ...
15.44 ns_user_del - Delete a specified user
15.45 ns_user_exists - Verify, if a user exists
15.46 ns_user_get - Get the properties for a specified local or LDAP user. ...
15.47 ns_user_idmap_get - Get an identity mapping for a Unix user.
15.48 ns_user_set - Modify an existing local user or add a new local ...
15.49 ping_tcp - Ping host using TCP
15.50 poweroff - Get the descriptions of the saved appliance's configurations
15.51 reboot - Reboot the appliance
15.52 reset_ugen_configuration - Reset the current USB devices configuration
15.53 restore_configuration - Restore an appliance's configuration from the most recent copy stored ...
15.54 restore_volume_services - Restore the volume services
15.55 save_configuration - Save appliance's configuration at a pre-defined location. The location in ...
15.56 save_user_configuration - Save appliance's configuration at a pre-defined location. The location in ...
15.57 set_dumpdir - Set a datapath for the directory that stores system crash ...
15.58 set_etchosts_rec - Add, replace or delete a record from the appliance's local ...
15.59 set_license_key - Update license key
15.60 ssh_bind - Bind a given (user, appliance) to the specified remote host ...
15.61 ssh_bind_add - Create the ssh-binding on the remote NexentaStor appliance
15.62 ssh_bind_delete - Delete the ssh-binding on the remote NexentaStor appliance
15.63 ssh_bind_v2 - Extension for the ssh_bind method, which enables you to use ...
15.64 ssh_bind_vip - Bind a standalone NexentaStor appliance to a cluster group virtual ...
15.65 ssh_check_binding - Verify whether the specified appliance is SSH-bound to the specified ...
15.66 ssh_list_bindings - Get all existing SSH bound hosts
15.67 ssh_unbind - SSH-unbind a given (user, appliance) from the specified remote host. ...
15.68 ssh_unbind_v2 - Extension for the ssh_unbind method, which enables you to use ...
15.69 ssl_bind - Add a new certificate to LDAP managed database
15.70 ssl_check_binding - Check whether the specified certificate exists in database
15.71 ssl_direct_bind - Add a new certificate to LDAP managed database
15.72 ssl_list_bindings - Get trusted host information for all existing certificates
15.73 ssl_list_certificates - Get certificate files
15.74 ssl_list_certinfos - Get certificate information for all existing certificates
15.75 ssl_unbind - Remove the specified certificate from the database - compare with ...
15.76 ssl_unbind_by_hostname - Remove a certificate from the LDAP managed database
15.77 stat_file - Collects and returns info for file path, including file type, ...
15.78 sysnotice_check - Check NMS sytem notice file
15.79 sysnotice_set - Update NMS sytem notice file
15.80 sysnotice_unset - Clear NMS sytem notice file
15.81 upgradable_packages - Get the list of packages to upgrade, when you run ...
15.82 upgradable_packages_check - Determine what packages require upgrade
15.83 upgrade_check - Check for appliance software upgrades
15.84 user_restore_configuration - Restore an appliance's configuration from the most recent copy stored ...
15.85 user_restore_volume_services - Restore volume services
16 Groups of Appliances Management
16.1 create - Create a new group of two or more NexentaStor appliances. ...
16.2 get_all - Get the list of all supported groups of all types. ...
16.3 get_all_members - Get the list of members of all groups.
16.4 get_group_types - Get the list of supported group types, for example ['basic']. ...
16.5 get_members - Get the list of members of the specified group. ...
17 JBOD Management
17.1 get_all_indicators - Get the status of the LED for each element in ...
17.2 get_elements - Get the list of elements. For type 'slot' all elements ...
17.3 get_failed_sensors - Get the list of sensors with failures. To get more ...
17.4 get_picture - Get a picture or an exception, if no item with ...
17.5 get_sensors - Get the list of sensors for a JBOD.
17.6 ident_off - Turn off the identification LED for a given element ...
17.7 ident_on - Turn on the identification LED for a given element ...
17.8 ident_state - Return the current status of an identification LED for a ...
17.9 ident_toggle - Switch the identification LED on a given element. It is ...
17.10 jbod_set_alias - Set user friendly name for a JBOD ID.
17.11 list_supported - Collect the information about the supported JBODs
17.12 rename_model - Rename JBOD's model
17.13 rescan - Update and re-read JBODs and disks. Use this method after ...
18 Job Management
18.1 cleanup_jobs - Delete the information aboioout the completed Jobs with expired 'autocleanup' ...
18.2 destroy_job - Delete/Cancel Job.
18.3 get_jobparams - Get the parameters of current Job
18.4 get_jobs - Get the list of current Jobs in a JSON format ...
18.5 get_jobtype_param_descs - Get the descriptions of the start parameters for the Job ...
18.6 get_jobtypes - Get the list of registered Job types
18.7 get_pid_by_unique_param - Get the list of Jobs for the specified unique startup ...
18.8 get_pids_by_param - Get the list of Jobs for the specified startup parameter ...
18.9 start_job - Start the Job with the specified parameters
19 Log Viewing Facility
19.1 get_linecount - Get the current position (line number) in the file ...
19.2 get_lines - Get the specified number of lines from the log file ...
19.3 get_tail - Get the specified number of lines from the end of ...
20 Logical and Physical Disk Management
20.1 blink_running - Verify that LED on a LUN blikns
20.2 blink_start - Start the LED blinking on a specified LUN
20.3 blink_stop - Stop LED blinking on a specified LUN
20.4 cache - Retrieve, enable and disable on-disk read and write cache. The ...
20.5 clear_slotmap - Clear the slotmap file content
20.6 disk_is_avail - Determine whether the specified disk (LUN) is available for usage, ...
20.7 get_lun_replacement_info - Get the LUN replacement information
20.8 get_slotmap - Get slot mapping information
20.9 have_slotmap - Check the existence of the slotmap file by type ...
20.10 hba_command - Execute the 'cfgadm -c operation' on each hbas
20.11 hba_list - Get the list of all HBAs by executing 'cfgadm -anl' ...
20.12 lunsync - Synchronize the LUNs and re-enumerate the devices in the appliance. ...
20.13 mounted_disks - Get the list of all mounted disks. The disk is ...
20.14 rescan - Refresh the states of LUNs.
20.15 resolve_to_vdevs - Retrieve the information about vdev that includes a specified LUN. ...
20.16 set_assignment - Set the assignment of a disk drive. Assignment defines the ...
20.17 set_slotmap - Set the slotmap parameters.
21 NMS Pool Management
21.1 disable - Disable NMS Pool support
21.2 enable - Enable NMS Pool support
21.3 get_pool - Get additional information about NMS Pool
21.4 kill_nms - Kill the process with specified PID
21.5 start_nms - Starts new NMS instance
22 Network Interface Management
22.1 change_aggr_props - Change the network agregation properties
22.2 check_static - Check the static network interface
22.3 create_aggr - Create an 802.3ad aggregated network interface (link).
22.4 create_aggr_with_props - Create link aggregation with specified parameters
22.5 create_ipalias - Create an IP alias (aka "logical IP interface").
22.6 create_ipmp_group - Create an IPMP group
22.7 create_vlan - Create a VLAN interface.
22.8 destroy_aggr - Destroy the specified aggregated link. This operation reverses the result ...
22.9 destroy_ipalias - Destroy an IP alias.
22.10 destroy_ipmp_group - Destroys and IPMP group
22.11 destroy_vlan - Destroy a VLAN interface.
22.12 get_aggr_props - Get the parameters of the aggregated interface
22.13 get_linkprops - Get the properties of the specified aggregated interface
22.14 get_max_mtu - Get the maximum MTU size supported by a given network ...
22.15 get_min_mtu - Get the minimum MTU size supported by a given network ...
22.16 get_names_by_type - Get the list of network interface names with the specified ...
22.17 get_other_drv_ifaces - Get the list of all network interfaces, that use the ...
22.18 ipaddr_to_dev - Get the interface name by IP address
22.19 is_capable - The method determines whether a given network interface driver has ...
22.20 is_drv_locked - The method evaluates the following condition: determines if one or ...
22.21 is_drv_reload_required - The method that determines whether the network interface driver must ...
22.22 refresh - Refresh the network interface object
22.23 set_dhcp - Configure the specified network interface using DHCP. Note that unlike ...
22.24 set_linkprop - Set the property of the network interface
22.25 set_macaddr - Set a MAC address for a given network interface. ...
22.26 set_mtu - Set the MTU for specified network interface.
22.27 set_static - Statically configure a network interface. Compare with com.nexenta.nms.NetworkInterface::set_dhcp. Use ...
22.28 set_static_extended - Statically configure the specified network interface with the additional parameters. ...
22.29 set_unconfigure - Unconfigure a network interface. This operation reverses the results of ...
23 Network Management
23.1 add_route - Add a route to a given destination using the specified ...
23.2 delete_route - Delete a route, a destination and a gateway.
23.3 find_gateway_hostname - Find the corresponding gateway for a given remote IP address. ...
23.4 gateway - Get the appliance's default gateway.
23.5 get_netmasks - Get the list of netmasks configured on the NexentaStor appliance. ...
23.6 get_nmv_props - Get the list of the Nexenta Management View (NMV) properties ...
23.7 get_nmv_url - Get the Nexenta Management View (NMV) URL for the appliance. ...
23.8 get_routes - Get all routes.
23.9 host_to_ipaddr - Get the IP address by hosname
23.10 is_port_free - Verify that the specified port is free
23.11 nameservers - Get name servers.
23.12 primary - Get the primary network interface.
23.13 remote_ipaddr_to_local_dev - Map a remote IP address to a local NIC for ...
23.14 set_gateway - Set the appliance's default gateway.
23.15 set_nameservers - Set the name servers. Appliance may have up to 3 ...
23.16 set_netmasks - Set netmasks on the NexentaStor appliance,
23.17 set_nmv_props - Set the NMV specific properties
23.18 set_primary - Set the primary network interface.
24 Network Services Management
24.1 confcheck - Check service state and configuration
24.2 get_conffiles_ - List of service configuration files
24.3 get_confmethods - The list of the available network service methods
24.4 get_confmethods_desc - Get the list of the available network service methods and ...
24.5 get_confopts - Returns the list of possible commands for setting up the ...
24.6 get_logfiles_ - List of service log files
24.7 get_smbadmlist - Returns information about the current workgroup or domain
24.8 set_confopts - Setup configuration method.
25 Network Storage Service
25.1 get_share_confopts - Get the static configuration options associated with the specified storage ...
25.2 get_shared_folders - Get all folders that are shared using the specified storage ...
25.3 get_shareopts - Get configuration options associated with the specified share
25.4 get_smf_netserv_services - Get the list of SMF network services that has any ...
25.5 is_folder_shared - Find out whether the specified folder is shared using the ...
25.6 share_folder - Share the specified folder using the specified storage access protocol ...
25.7 smf_netserv_status - Get the status of SMF network services.
25.8 unshare_all - Unshare the specified folder globally, as far as all or ...
25.9 unshare_folder - Unshare the specified folder from access using the specified storage ...
26 Nexenta Management Server
26.1 append_log - Add lines to Server log
26.2 event_broadcast - Create event broadcast message
26.3 fma_event_callback - Passthrough fma event to report a fault
26.4 get_const - Get predefined system constants
26.5 get_extended_lock_info - Get an extended lock information.
26.6 get_locks - Get all existing NMS locks.
26.7 get_reply_timeout - Get Nexenta Management Server D-Bus reply timeout.
26.8 is_locked_by_client - Check if Server is locked by client
26.9 list_props - Get all NMS properties (name, value pairs) and their descriptions. ...
26.10 nmdtrace_status - Get the status of the Nexenta DTrace statistic service. ...
26.11 register_local_client - Register a local NMS client - an external local process ...
26.12 reread_config - Re-read server configuration.
26.13 restart_nmcd - Restart Nexenta Management Console daemon.
26.14 restart_nmdtrace - Restart Nexenta DTrace daemon. Nexenta DTrace Service is a daemon ...
26.15 set_reply_timeout - Set the reply timeout for Nexenta Management Server D-Bus. ...
26.16 unregister_local_client - Unregister a local NMS client.
27 Plugin
27.1 get_group_names - Get the array of all, or filtered group names. ...
27.2 get_group_plugins - Get the list of all plugins in a group ...
27.3 get_group_props - Get the dictionary with all the properties of a group, ...
27.4 get_ipc_info - Get the interface dicitonary { ipc_name => (name, suffix)} for ...
27.5 get_ipc_srvpool - Determines if a specified plugin can work with Server Pool ...
27.6 get_plugins_by_caps - Get all the plugins with required capability
27.7 get_restorable_plugins - Get all plugins, which can be restored from the saved ...
27.8 list_remote_ - Get { plugin => plugin_properties } dictionary of all available ...
27.9 preinst_check - Plugin pre-installation verification, determines, if a reboot is required or ...
27.10 resolve_lun_to_services - Get the list of all services available for a given ...
27.11 resolve_zfsname_to_services - Get the list of services that run on a ZFS ...
28 Reporting Facility (Services, Performance, Capacity)
28.1 send - Send a report to the general e-mail address
29 SMTP Mailer
29.1 check_support_request_ready - Check if the diagnostic logs are collected to be send ...
29.2 prepare_support_request - Collect the diagnostic messages and prepare the support request ...
29.3 save_support_request - Save the support request in a specified folder
29.4 send_support_request - Prepare and send support request
29.5 send_test - Send test e-mail
30 Service Account Management
31 Service Management Facility (SMF)
31.1 clear - Clear maintaince state of a service
31.2 disable - Disable an SMF service
31.3 enable - Enable an SMF service. Clears the maintenance state, if a ...
31.4 fmri_validate - Check, if a service exists
31.5 get_logfile - Get the logfile path for an SMF service
31.6 get_state - Get the current state of the specified SMF service ...
31.7 reread_config - Re-read and re-apply a service configuration. The operation updates the ...
31.8 restart - Restart an SMF service. The operation is equivalent to com.nexenta.nms.Smf::enable ...
31.9 wait_for - Wait for the specific state of service
32 Snapshot Management
32.1 create - Create (ie, take) snapshots, recursively or non-recursively, depending on the ...
32.2 get_groupspace - Get groupspace for specified parameters
32.3 get_groupspace_types - Get available groupspace types
32.4 get_snapshot_names - Get the list of existing snapshots for the specified folder, ...
32.5 get_userspace - Get userspace specified parameters
32.6 get_userspace_types - Get available userspace types
32.7 has_zfs_prop - Determine whether zfs property exists or not
32.8 rename - Give a new name to snapthot
32.9 rollback - Rollback a folder to a given snapshot
33 Statistic Collection
34 Support information collector
34.1 get_sub_categories - Get sub categories
34.2 get_top_categories - Get top categories
35 System Upgrade, Rollback and Checkpoint Management
35.1 activate_rootfs - Activate, that is make default, the specified system checkpoint. This ...
35.2 destroy_rootfs - Destroy the specified system checkpoint. Note that the appliance will ...
35.3 get_rootfs_names - Get the names of all existing root filesystems a.k.a system ...
35.4 get_rootfs_prop - Get the value of specified property of the system checkpoint ...
35.5 get_rootfs_props - Get properties of the specified system checkpoint
35.6 get_upgrade_info - Get detailed appliance software upgrade status
36 User scripts Management
36.1 create - Create a new user defined script
37 Virtual Automatic Storage Service
37.1 can_tier_copy_acls - Checks if you can copy the ACLs using RSYNC ...
37.2 execute - Execute a (auto-) service instance. This SA-API method enables you ...
37.3 get_sock_stats - Get just-in-time transport statistics. The method can be used to ...
37.4 is_daemon - Find out whether the service is a daemon
37.5 is_running - Find out whether the service is currently running
37.6 is_scheduled - Find out whether the service is scheduled
37.7 seconds_until_next_run - For a given auto-service, returns the number of seconds remaining ...
38 Virtual Runner
38.1 disable - Stop the execution of a runner. The runner must be ...
38.2 enable - Enable the specified runner. The runner must be registered (see ...
38.3 execute - Execute the specified runner. The operation enables you to run ...
38.4 get_init_params - Get the initial parameters for the specified Script Runner ...
38.5 get_init_tunables - Get the initial tunables for the specified Script Runner ...
38.6 get_tunables - Get the list of runner's tunables and their descriptions. For ...
38.7 is_registered - Check whether the specified runner is registered with the appliance. ...
38.8 register - Register the specified runner. The operation validates runner's parameters and ...
38.9 reset - Destroy job which is linked to specified Runner
38.10 set_tunable - Modify the runner's (tunable) property value. A given runner may ...
38.11 unregister - Unregister the specified runner. The operation reverses the effect of ...
39 Volume (Pool)
39.1 attach_lun - Attach a to an existing mirror. Otherwise, if mirror ...
39.2 clear_lun - Clear the device errors in a volume. The device errors ...
39.3 create_reserve - Creates new reserve folder
39.4 detach_lun - Detach device from a mirror
39.5 free_reserve - Remove a folder that contains emeregency reserve
39.6 get_all_names - Get the list of names of all child objects that ...
39.7 get_available_spares - Get the list of disks that can be used as ...
39.8 get_groupspace - Get the groupspace parameters
39.9 get_groupspace_types - Get the available groupspace types
39.10 get_import_volumes - Get the information about all, or selected volumes that can ...
39.11 get_luns - Get the list of LUNs for a given volume ...
39.12 get_luns_for_all_volumes - Get the list of all LUNs that are used by ...
39.13 get_prop_valid_values - Get the valid range and/or enumeration for a given volume's ...
39.14 get_shared_volumes - Get the list of all volumes that are currently shared ...
39.15 get_status - Get the volume's status
39.16 get_userspace - Get the userspace parameters
39.17 get_userspace_types - Get available userspace types
39.18 get_version_info - Get volume's ZFS version
39.19 has_reserve - Determine if a volume already has emergency reserve folder ...
39.20 has_zfs_prop - Determine whether zfs property exists or not
39.21 has_zpool_prop - Determine whether zpool property exists or not
39.22 history - Get volume history records, in terms of executed ZFS commands ...
39.23 offline_lun - Take the physical device offline. While the device is offline, ...
39.24 online_lun - Bring the physical device online. This operation is not applicable ...
39.25 recover_faulted_luns - Recover faulted devices in a volume. This operation is currently ...
39.26 remove_lun - Permanently remove a hot spare device from the volume. ...
39.27 replace_lun - Replace device in a mirror. The operation replaces with ...
39.28 resolve_lun_to_volumes - Resolve LUN to its container volume(s).
39.29 set_property - Set a zpool property
39.30 upgrade - Upgrade volume's ZFS version. WARNING: This operation may affect availability ...
39.31 vol_create - Create a volume
39.32 vol_export - Export a volume. This operation exports a volume and cleanups/destroys: ...
39.33 vol_grow - Grow a volume
39.34 vol_import - Import a volume
40 Zvol (Emulated Volume-based Block Device)
40.1 clone - Clone a zvol. The operation results in a writable zvol ...
40.2 create - Create a new zvol. NexentaStor provides an easy iSCSI and ...
40.3 create_snapshot - Snapshot a given zvol
40.4 create_with_props - Create a new zvol. This API method enables you to ...
40.5 get_prop_valid_values - Get a valid range and/or enumeration for a given zvol's ...
40.6 has_zfs_prop - Determine if zfs property exists or not
41 com.nexenta.nms.Profiler
42 iSCSI Initiator
42.1 get_all_luns - Get the list of all iSCSI attached LUNs (disks). ...
42.2 get_connections - Get all connections for a given iSCSI session between the ...
42.3 get_defaults - Get the Initiator parameters. The list includes: InitiatorName, InitiatorAlias, AuthMethod, ...
42.4 get_discovery - List (TargetName, TargetAddress, TPGT) triplets for all configured discoveries. ...
42.5 get_discovery_state - Get the discovery state for the discovery method.
42.6 get_discovery_status - Get the discovery status. Returns more detailed information than 'get_discovery_state' ...
42.7 get_luns - Get the list of LUNs for the specified iSCSI Target. ...
42.8 get_sessions - Get the list of active iSCSI sessions.
42.9 get_target_config - Get the iSCSI Target configuration. The list of configurable parameters ...
42.10 get_target_props - Get the iSCSI Target default and user-defined parameters.
42.11 get_targets - List the available iSCSI Targets. The result can be used ...
42.12 get_volumes - Get the list of volumes which are connected through iSCSI ...
42.13 list_discovery - Get the list of discovery settings for the discovery method ...
42.14 remove_target - Remove a set of specified target parameters
42.15 set_default - Update the Initiator parameter. The list includes: InitiatorName, InitiatorAlias, AuthMethod, ...
42.16 set_target_config - Update the iSCSI Target configuration.
42.17 setup_discovery - Setup iSCSI discovery
43 Examples and Usage Cases
43.1 C/C++
43.2 Perl
43.3 Python
43.4 Ruby
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:
LANGUAGE COMMENT
C/C++ SA-API is layered on top native libraries for Windows, Linux and MacOSX operating systems. The libraries
are provided with the NexentaStor software development kit (SDK). NexentaStor SDK contains tutorials and
examples written in C and C++.
Perl SA-API uses Perl D-Bus bindings realized via Net::DBus package. The package comes with Perl tutorials and
Perl examples.
Python SA-API utilizes Pythin D-Bus bindings. Similarly, the Python D-Bus Tutorial contains easy introduction and
multiple Python examples.
Ruby SA-API is layered on top of Ruby D-bus bindings. The Ruby D-Bus project contains reference
documentation, Ruby tutorials and examples.
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
DOCUMENT COMMENT
CONVENTION
value1 | Enumeration. The '|' delimited list denotes enumerated list of values. For instance, 0 | 1 specifies a
value2 ... boolean value (passed as a parameter or returned by an SA-API method call) that can have one of the
listed values: 0 or 1
true, false As far as SA-API and this document, "true" and "non-zero" on one hand, and "false" and "zero" on
another are used interchangeably. There are no special "true" and "false" values. The preferred way to
pass a boolean value in a method call is to specify 1, although you may use any non-zero value
array of (item- Array of items of the type 'item-type'. In this document, round brackets () are used to denote linear
type) arrays containing items of the same type. For instance, 'array of (string)' means arrays of strings.
Specification 'array of (string) foo()' indicates that the method foo() returns array of strings. Simlarly,
'bar (array of (string) param)' means that the type of the 1st argument of the method bar() is an array
of strings. For more information on the SA-API data types, please see Section Data Types below.
dictionary Dictionary of records, whereby each record has a key of type 'key-type' and a value of type 'value-type'.
{key-type => By convention, curly braces {} denote dictionaries. For more information on the SA-API data types,
value-type} please see Section Data Types below
TERM COMMENT
SA-API NexentaStor Storage Appliance application programming interface
NMS Nexenta Management Server, the sole provider of the SA-API
NMC Nexenta Management Console, the appliance's management CLI
Volume NexentaStor volume is a ZFS pool with certain additional attributes. There is a one-to-one relationship
between a volume and the underlying ZFS pool
Folder NexentaStor folder is a ZFS filesystem
AutoSnap, Types of appliance's storage services. For more information, please refer to NexentaStor User Guide
AutoTier,
AutoSync,
AutoCdp
Runner Triggers, Collectors, Reporters, and Indexers - also commonly called "runners" - are pluggable modules
that perform specific Fault Management, Performance Monitoring, Reporting, and archive Indexing tasks.
All specific runners inherit Virtual Runner SA-API interfaces
Lun Physical and logical drives, attached to the appliance directly or via iSCSI or FC SAN, are commonly
called LUNs. The terms "LUN", "hard drive" and "disk" are used interchangeably
Zvol Emulated (virtual) block device based on a given appliance's volume
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.
List of interface ojects
SA-API interface D-Bus name Reference section Inherits
(proxy) object
com.nexenta.nms.Object 'Abstract Class' Virtual Base Object
abstract container 'Abstract Class' Virtual Container Virtual Base Object
NZA::appl_backup '/Root/ApplianceBackup' Appliance Backup Virtual Base Object
NZA::auto_scrub '/Root/Smf/AutoService/AutoScrub' AutoScrub (volume Virtual Automatic Storage
scrubbing) Service Service Service Management
Facility (SMF) Virtual
Container Virtual Base Object