26.4. Use of the libStorageMgmt

To use libStorageMgmt interactively, use the lsmcli command.
The lsmcli tool requires two things to run:
  • A Uniform Resource Identifier (URI) which is used to identify the plug-in to connect to the array and any configurable options the array requires.
  • A valid username and password for the array.
URI has the following form:
plugin+optional-transport://username@host:port/?query-string-parameters
Each plug-in has different requirements for what is needed.

Example 26.1. Examples of different plug-in requirements

Simulator plug-in that requires no user name or password

sim://

NetApp plug-in over SSL with user name root

ontap+ssl://root@filer.company.com/

SMI-S plug-in over SSL for EMC array

smis+ssl://admin@provider.com:5989/?namespace=root/emc

There are three options to use the URI:
  1. Pass the URI as part of the command.
    $ lsmcli -u sim://...
  2. Store the URI in an environmental vairable.
    $ export LSMCLI_URI=sim:// && lsmcli ...
  3. Place the URI in the file ~/.lsmcli, which contains name-value pairs separated by "=". The only currently supported configuration is 'uri'.
Determining which URI to use needs to be done in this order. If all three are supplied, only the first one on the command line will be used.
Supply the password by specifying -P on the command line or by placing it in an environmental variable LSMCLI_PASSWORD.

Example 26.2. Examples of lsmcli

An example for using the command line to create a new volume and making it visible to an initiator.
List arrays that are serviced by this connection.
$ lsmcli list --type SYSTEMS
ID     | Name                          | Status
-------+-------------------------------+--------
sim-01 | LSM simulated storage plug-in | OK
List storage pools.
$ lsmcli list --type POOLS -H
ID   | Name          | Total space          | Free space           | System ID
-----+---------------+----------------------+----------------------+-----------
POO2 | Pool 2        | 18446744073709551616 | 18446744073709551616 | sim-01
POO3 | Pool 3        | 18446744073709551616 | 18446744073709551616 | sim-01
POO1 | Pool 1        | 18446744073709551616 | 18446744073709551616 | sim-01
POO4 | lsm_test_aggr | 18446744073709551616 | 18446744073709551616 | sim-01
Create a volume.
$ lsmcli volume-create --name volume_name --size 20G --pool POO1 -H
ID   | Name        | vpd83                            | bs  | #blocks  | status | ...
-----+-------------+----------------------------------+-----+----------+--------+----
Vol1 | volume_name | F7DDF7CA945C66238F593BC38137BD2F | 512 | 41943040 | OK     | ...
Create an access group with an iSCSI initiator in it.
$ lsmcli --create-access-group example_ag --id iqn.1994-05.com.domain:01.89bd01 --type ISCSI --system sim-01
ID                               | Name       | Initiator ID                     |SystemID
---------------------------------+------------+----------------------------------+--------
782d00c8ac63819d6cca7069282e03a0 | example_ag | iqn.1994-05.com.domain:01.89bd01 |sim-01
Create an access group with an iSCSI intiator in it:
$ lsmcli access-group-create --name example_ag --init iqn.1994-05.com.domain:01.89bd01 --init-type ISCSI --sys sim-01
ID                               | Name       | Initiator IDs                    | System ID
---------------------------------+------------+----------------------------------+-----------
782d00c8ac63819d6cca7069282e03a0 | example_ag | iqn.1994-05.com.domain:01.89bd01 | sim-01
Allow the access group visibility to the newly created volume:
$ lsmcli access-group-grant --ag 782d00c8ac63819d6cca7069282e03a0 --vol Vol1 --access RW
The design of the library provides for a process separation between the client and the plug-in by means of inter-process communication (IPC). This prevents bugs in the plug-in from crashing the client application. It also provides a means for plug-in writers to write plug-ins with a license of their own choosing. When a client opens the library passing a URI, the client library looks at the URI to determine which plug-in should be used.
The plug-ins are technically stand alone applications but they are designed to have a file descriptor passed to them on the command line. The client library then opens the appropriate Unix domain socket which causes the daemon to fork and execute the plug-in. This gives the client library a point to point communcation channel with the plug-in. The daemon can be restarted without affecting existing clients. While the client has the library open for that plug-in, the plug-in process is running. After one or more commands are sent and the plug-in is closed, the plug-in process cleans up and then exits.
The default behavior of lsmcli is to wait until the operation is completee. Depending on the requested operations, this could potentially could take many hours. To allow a return to normal usage, it is possible to use the -b option on the command line. If the exit code is 0 the command is completed. If the exit code is 7 the command is in progress and a job identifier is written to standard output. The user or script can then take the job ID and query the status of the command as needed by using lsmcli --jobstatus JobID. If the job is now completed, the exit value will be 0 and the results printed to standard output. If the command is still in progress, the return value will be 7 and the percentage complete will be printed to the standard output.

Example 26.3. An asynchronous example

Create a volume passing the -b option so that the command returns immediately.
$ lsmcli volume-create --name async_created --size 20G --pool POO1 -b JOB_3
Check to see what the exit value was, remembering that 7 indicates the job is still in progress.
$ echo $?
7
Check to see if the job is completed.
$ lsmcli job-status --job JOB_3
33
Check to see what the exit value was, remembering that 7 indicates the job is still in progress so the standard output is the percentage done or 33% based on the above screen.
$ echo $?
7
Wait some more and check it again, remembering that exit 0 means success and standard out displays the new volume.
$ lsmcli job-status --job JOB_3 
ID   | Name          | vpd83                            | Block Size  | ...
-----+---------------+----------------------------------+-------------+-----
Vol2 | async_created | 855C9BA51991B0CC122A3791996F6B15 | 512         | ...
For scripting, pass the -t SeparatorCharacters option. This will make it easier to parse the output.

Example 26.4. Scripting examples

$ lsmcli list --type volumes -t#
Vol1#volume_name#049167B5D09EC0A173E92A63F6C3EA2A#512#41943040#21474836480#OK#sim-01#POO1
Vol2#async_created#3E771A2E807F68A32FA5E15C235B60CC#512#41943040#21474836480#OK#sim-01#POO1
$ lsmcli list --type volumes -t " | "
Vol1 | volume_name | 049167B5D09EC0A173E92A63F6C3EA2A | 512 | 41943040 | 21474836480 | OK | 21474836480 | sim-01 | POO1
Vol2 | async_created | 3E771A2E807F68A32FA5E15C235B60CC | 512 | 41943040 | 21474836480 | OK | sim-01 | POO1
$ lsmcli list --type volumes -s
---------------------------------------------
ID         | Vol1                            
Name       | volume_name                     
VPD83      | 049167B5D09EC0A173E92A63F6C3EA2A
Block Size | 512                             
#blocks    | 41943040                        
Size       | 21474836480                     
Status     | OK                              
System ID  | sim-01                          
Pool ID    | POO1                            
---------------------------------------------
ID         | Vol2                            
Name       | async_created                   
VPD83      | 3E771A2E807F68A32FA5E15C235B60CC
Block Size | 512                             
#blocks    | 41943040                        
Size       | 21474836480                     
Status     | OK                              
System ID  | sim-01                          
Pool ID    | POO1                            
---------------------------------------------
It is recommended to use the Python library for non-trivial scripting.
For more information on lsmcli, refer to the man pages or the command lsmcli --help.