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

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.

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.

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

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

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.

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

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

Add a custom naming convention using the ViPR Controller UI

System administrators can add custom naming conventions using the UI.

Before you begin

Review the maximum name length and the list of valid characters for the resource name on the physical system for which you are adding a custom naming convention.
Only System Administrators can add custom naming conventions.
ViPR Controller does not enforce uniqueness for your custom name so ensure that your naming convention produces unique names to avoid conflicts.

Procedure

Log into the ViPR Controller UI with System Administrator privileges.
Select Physical Assets > Controller Config
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.
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.

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.
Click Add.
Select the Scope Type.
Select the Scope Value.
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 (*).
Click Save.

Add a custom naming convention using the REST API

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

Before you begin

Authenticate with the ViPR Controller REST API as a Security Administrator.
Review the maximum name length and the list of valid characters for the resource name on the physical system for which you are adding a custom naming convention.
ViPR Controller does not enforce uniqueness for your custom name so ensure that your naming convention produces unique names to avoid conflicts.
The EMC ViPR Controller REST API Reference provides a complete list of parameters for the REST API methods used in this discussion. You can access this document from the ViPR Controller Product Documentation Index.

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

Procedure

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

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>

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>

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>

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.

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.

REST API Calls to Manage Custom naming conventions
REST API Call	Description
GET /config/controller	Get all configuration types.
PUT /config/controller/{ID}	Modify a custom naming convention. <config_update> <value>ZN_{host_name.FIRST(8)}_{hba_port_wwn}_{array_port_wwn}</value> </config_update>
POST /config/controller/{ID}/deactivate	Delete a custom naming convention.
GET /config/controller/search?parameter={search_parameter}	Search for a configuration type. You can search by a single parameter or multiple parameters. The search parameters are: config_type scope name system_default Sample search using config_type: GET /config/controller/search?config_type=SanZoneName Sample search using config_type and scope: GET /config/controller/search?config_type=SanZoneName&scope=systemType.brocade Sample search using name: GET /config/controller/search?name=systemType.brocade.SanZoneName Sample search for the default values of all configuration types: GET /config/controller/search?system_default=true Sample search for the default value of the specified config_type GET /config/controller/search?config_type=SanZoneName&system_default=true
POST /config/controller/{ID}/register	Make the naming convention active. When you use POST /config/controller to create a new naming convention, it is automatically registered by ViPR Controller.
POST /config/controller/{ID}/deregister	Deregister the naming convention so it is not used.

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

Table of Contents

Before you begin

Procedure

Before you begin

Procedure