Customize the Names of Resources Created by ViPR Controller on Physical Systems

Table of Contents

Overview

By default, as you add physical assets ViPR Controller creates a number of resources on the physical system, such as masking views and zones using a single global hard-coded naming convention for each type of resource. However, you can override the default and provide your own naming convention for several types of resources .

If you define your own naming convention for a resource, ViPR Controller uses your convention, otherwise, the default naming convention is used to name the resource. Your custom naming convention applies to all new instances of that resource. It does not rename existing instances.

Custom naming conventions can be configured for a global or per system type scope.

The name that is generated from your custom naming convention must adhere to the following restrictions imposed by the storage or network system to which it applies:
  • The name can not exceed the maximum length for the resource.
  • The name must only include characters that are part of the valid characters set for the resource.
Note Image
ViPR Controller does not enforce uniqueness for your custom name so ensure that your naming convention produces unique names to avoid conflicts.

You can modify the naming conventions for the following ViPR Controller resources.

Note Image
VMAX Masking for Host Masking View Name, Cluster Masking View Name, Host Storage Group Name, Cluster Storage Group Name, Host Port Group Name and Cluster Port Group Name is not supported for a clone with the BCV attribute.

  • San Zoning
    • Zoning - scope can be set globally or by system type
  • VMAX Masking
    • Host Masking View Name
    • Cluster Masking View Name
    • Host Storage Group Name
    • Cluster Storage Group Name
    • Host Cascaded IG Name
    • Cluster Cascaded IG Name
    • Host Cascaded SG Name
    • Cluster Cascaded SG Name
    • Host Initiator Group Name
    • Cluster Initiator Group Name
    • Host Port Group Name
    • Cluster Port Group Name
  • VNX Storage Groups
    • Host Storage Group Name
  • VPLEX
    • Storage View Name
  • XtremIO
    • Volume Folder Name
    • Initiator Group Name
    • Host Initiator Group Folder Name
    • Cluster Initiator Group Folder Name
  • HDS
    • Host Storage Domain Name
    • Host Storage Domain Nick Name

Back to Top

Naming policy syntax

When you create a custom naming convention for a resource, it must follow a specific syntax.

For each of the resources for which you can provide a custom naming convention, there are a set of variables and functions that you can use to create the name. The functions are the same for all of the resources, but the variables will differ by resource.

A custom naming convention can include the following:
  • Literal strings.
  • Special characters, such as underscores (_), that are part of the valid character set for the resource. When using a dot (.) you must preface it with a backslash (\), such as emc\.com.
  • Variable name surrounded by curly brackets.
  • Function,
    • Applied to an individual variable string to select certain parts of the string value for the name, using the syntax <variable_name>.<function_name>(<function values>)
    • Applied to the entire custom naming mask, using the syntax, (<entire_name_mask>).<function_name>(<function_values>)
Refer to the documentation for the physical system for the list of valid characters for the literal strings and special characters for each resource.
In this example, host_name and array_serial_number are variables , and FIRST and LAST are functions that are applied to those variables to select the part of the string that is to become part of the custom name. The name of the resource will be comprised of the first 12 characters of the host name, followed by an underscore (_) and the last 3 characters of the array serial number, followed by _CSG. 
{host_name.FIRST(12)}_{array_serial_number.LAST(3)}_CSG
Note Image
Any function being applied to a variable is within the curly brackets for that variable.

If any variables contain invalid characters for the resource name, by default ViPR Controller removes those invalid characters. For example, if the zone name variable, {host_name}, contains ".", ViPR Controller removes them after all the string functions are applied.

Back to Top

Available functions

For each of the resources for which you can provide a custom naming convention, there are a set of variables and functions that you can use to create the naming policy. The functions are the same for all of the resources, but the variables will differ by resource.

The functions that are available are described in the table. The general format for using a function is: {<variable_name>.<function_name>(<function_values>)}

Note Image
These examples refer to the variable host_name which corresponds to the Host field when you added the host to ViPR Controller. The host_name variable is the host FQDN or IP address. There is also a host_assigned_name variable that you can use in some of your custom names that corresponds to the Name field when you added the host. The host_assigned_name variable is just a label that you can assign to the host.

Function Description
FIRST Use the first n characters of the string value of a variable.
For example, 
{host_name.FIRST(60)}
LAST Use the last n characters of the string value of a variable.
For example, 
{array_serial_number.LAST(3)}
REPLACE Replace a character with another character.
In this example, all of the dashes in the string value of the variable, hba_port_wwn, are replaced with a null string, essentially deleting all of the dashes. 
{hba_port_wwn.REPLACE("-","")}
SUBSTRING Use part of a string. You specify the beginning and ending character of the string that defines the substring. In this example, only the characters 3-9 are selected from the host_name variable to be part of the custom name. 
{host_name.SUBSTRING(3,9)}
TOLOWER Change all characters in the specified string to lower case. 
{host_name.TOLOWER()}
TOUPPER Change all characters in the specified string to upper case. 
{host_name.TOUPPER()}
TRIM Remove leading and trailing characters from a string. The TRIM function can be used on the final generated name or on the individual variable strings.
To apply the function to the entire generated name, the syntax is as shown. Note that the entire custom name mask is contained within parentheses. 
({cluster_name.FIRST(19)}_{host_name.FIRST(2)}).TRIM("_")
To apply the function to an individual variable, the syntax is as shown. 
({cluster_name.FIRST(19)}).TRIM(";")
You can also concantenate functions on an individual variable, with the functions being evaluated from left to right. In this example, the name would use the first 15 characters of the value of the variable host_name and change those characters to all lowercase. 
{host_name.FIRST(15).TOLOWER()}
Back to Top

Add a custom naming convention using the ViPR Controller UI

System administrators can add custom naming conventions using the UI.

Before you begin

Procedure

  1. Log into the ViPR Controller UI with System Administrator privileges.
  2. Select Physical Assets > Controller Config
  3. Select the tab that corresponds to the physical system for which you are creating a new custom naming convention. Your choices are: SAN Zoning, VMAX Masking, VNX Storage Groups, VPlex, XtremIO, or HDS.
  4. Select the type of name you are creating. For example, if you selected VMAX Masking, you can select Cluster Storage Group Name from the name list.
    Note Image
    You will see the default ViPR Controllernaming convention

    with the Scope Type and Scope Value in light grey text. You cannot select the default convention and you cannot change the default naming convention. However, once you add a new naming convention, ViPR Controller will use your naming convention instead of the default.
  5. Click Add.
  6. Select the Scope Type.
  7. Select the Scope Value.
  8. Type the Value of your custom naming convention.
    Following the naming convention syntax, use the available functions and the variables for the selected name. The variables for the name you selected are listed on the bottom of the screen. In addition, the variables that are recommended to ensure a unique name are marked with an asterisk (*).
  9. Click Save.
Back to Top

Add a custom naming convention using the REST API

System administrators can add custom naming conventions using the REST API.

Before you begin

In this example, a custom naming convention is being added for the configuration type, SanZoneName, which determines how ViPR Controller names SAN zones.

Procedure

  1. Determine the name of the controller configuration for which you want to provide a custom naming convention by sending GET /config/controller/types. This method returns a list of the names of all of the available controller configurations. If you already know the name, then you can skip to step 2.
    Request 
    GET https://<ViPR_Controller_VIP>:4443/config/controller/types
Content-Type: application/xml
X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
    Response
    Note Image
    For readability, only part of the list of controller configuration names is shown in this response. 

    HTTP 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config_types>
    <config_type>
        <name>SanZoneName</name>
        <link rel="self" href="/config/controller/types/SanZoneName"/>
    </config_type>
    <config_type>
        <name>VNXHostStorageGroupName</name>
        <link rel="self" href="/config/controller/types/VNXHostStorageGroupName"/>
    </config_type>
    <config_type>
        <name>VMAXHostMaskingViewName</name>
        <link rel="self" href="/config/controller/types/VMAXHostMaskingViewName"/>
    </config_type>
    <config_type>
        <name>VMAXClusterMaskingViewName</name>
        <link rel="self" href="/config/controller/types/VMAXClusterMaskingViewName"/>
    </config_type>
    <config_type>
        <name>VMAXHostStorageGroupName</name>
        <link rel="self" href="/config/controller/types/VMAXHostStorageGroupName"/>
    </config_type>
</config_types>
  2. Retrieve the variables that define the configuration type by sending GET /config/controller/types/<configuration_type>. These variables can be used, along with the available functions, to create your custom naming convention.
    Each configuration type includes one or more scopes that can be defined. The response includes the type of scope and the valid values for the scope. In addition, each variable that is returned includes the name of the variable, sample values, and whether the variable is recommended for inclusion in your custom naming convention to produce a unique resource name.
    Request 
    GET https://<ViPR_Controller_VIP>:4443/config/controller/types/SanZoneName
Content-Type: application/xml
X-SDS-AUTH-TOKEN: <AUTH_TOKEN>
    Response 
    HTTP 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config_type>
    <name>SanZoneName</name>
    <rules>
        <rule>IllegalCharsConstraint</rule>
        <rule>MaxLengthConstraint</rule>
        <rule>IllegalFirstCharConstraint</rule>
    </rules>
    <scopes>
        <scope>
            <type>global</type>
            <value>default</value>
        </scope>
        <scope>
            <type>systemType</type>
            <value>mds</value>
            <value>brocade</value>
        </scope>
    </scopes>
    <type>String</type>
    <variables>
        <variable>
            <recommended>true</recommended>
            <display_name>hba_port_wwn</display_name>
            <sample_value>10:00:00:90:FA:34:4C:EE</sample_value>
        </variable>
        <variable>
            <recommended>false</recommended>
            <display_name>hba_name</display_name>
            <sample_value>hba01</sample_value>
        </variable>
        <variable>
            <recommended>true</recommended>
            <display_name>array_port_wwn</display_name>
            <sample_value>50:00:09:73:00:18:95:24</sample_value>
        </variable>
        <variable>
            <recommended>false</recommended>
            <display_name>array_port_name</display_name>
            <sample_value>FA-10E:0</sample_value>
        </variable>
        <variable>
            <recommended>false</recommended>
            <display_name>host_name</display_name>
            <sample_value>xyz015.company.com</sample_value>
        </variable>
        <variable>
            <recommended>false</recommended>
            <display_name>host_type</display_name>
            <sample_value>Windows</sample_value>
        </variable>
        <variable>
            <recommended>false</recommended>
            <display_name>vsan/fabric</display_name>
            <sample_value>fid3100</sample_value>
        </variable>
        <variable>
            <recommended>false</recommended>
            <display_name>array_serial_number</display_name>
            <sample_value>000123456789</sample_value>
        </variable>
        <variable>
            <recommended>false</recommended>
            <display_name>array_type</display_name>
            <sample_value>vmax</sample_value>
        </variable>
    </variables>
</config_type>
  3. Use POST /config/controller/preview to preview how variables will appear in your custom name to ensure that you generate a unique name with your custom naming convention.
    The request payload includes your custom naming convention for the configuration type, the scope, and the variable name and value that you want to preview.
    Request 
    POST https://<ViPR_Controller_VIP>:4443/config/controller/preview
Content-Type: application/xml
X-SDS-AUTH-TOKEN: <AUTH_TOKEN>

<config_preview>
     <config_type>SanZoneName</config_type>
     <value>ZN_{host_name.FIRST(8)}_{hba_port_wwn}_{array_port_wwn}</value>
     <scope>
          <type>systemType</type>
          <value>brocade</value>
     </scope>
     <preview_variable>
          <variable_name>host_name</variable_name>
          <value>abc12570.mycompany.com</value>
     </preview_variable>
</config_preview>
    Response 
    HTTP 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<preview>
     <resolved_value>ZN_abc12570_10000090FA344CEE_5000097300189524</resolved_value>
</preview>
  4. Add the custom naming convention value for the configuration type using POST /config/controller.
    Request 
    POST https://<ViPR_Controller_VIP>:4443/config/controller/
Content-Type: application/xml
X-SDS-AUTH-TOKEN: <AUTH_TOKEN>

<config_create>
     <config_type>SanZoneName</config_type>
     <value>ZN_{host_name.FIRST(8)}_{hba_port_wwn}_{array_port_wwn}</value>
     <scope>
          <type>systemType</type>
          <value>brocade</value>
     </scope>
</config_create>
    Response 
    HTTP 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<config>
    <id>urn:storageos:CustomConfig:f1c798ac-8a21-4d1c-a069-59c34131d3b5:vdc1</id>
    <link rel="self" href="/config/controller/urn:storageos:CustomConfig:f1c798ac-8a21-4d1c-a069-59c34131d3b5:vdc1"/>
    <name>systemType.brocade.SanZoneName</name>
    <tags/>
    <config_type>
        <name>SanZoneName</name>
        <link rel="self" href="/config/controller/types/SanZoneName"/>
    </config_type>
    <registered>true</registered>
    <scope>
        <type>systemType</type>
        <value>brocade</value>
    </scope>
    <system_default>false</system_default>
    <value>ZN_{host_name.FIRST(8)}_{hba_port_wwn}_{array_port_wwn}</value>
</config>
    ViPR Controller has a default naming convention for each of the configuration types for which you can add a new naming convention. You cannot change the default naming convention for a configuration type. But once you add a new naming convention for a configuration type, then ViPR Controller uses your new convention, instead of the default convention. The system_default setting of false in the response indicates that this value is not the default ViPR naming convention.
Back to Top

Additional REST API calls to manage custom naming conventions

The table shows some important APIs that are used to manage custom naming conventions, in addition to the APIs already described in the example.

Back to Top