The Tours of the Black Prompt series so far:
Today we’re getting into more advanced CLI operations for clustered Data ONTAP with field options, queries, and operators.
Field Options
In Part 2, we looked at enabling a session-level setting that would force the display of all possible fields for a given command’s tabular output, but there’s a lot more flexibility around which fields can be displayed than just a defaults-or-everything approach.
Every command provides a “-fields” parameter which allows you to granularly specify which fields will be displayed as part of the output.
cdot_mba1::> vol show
(volume show)
Vserver Volume Aggregate State Type Size Available Used%
--------- ------------ ------------ ---------- ---- ---------- ---------- -----
cdot_mba1-01
vol0 aggr0 online RW 851.5MB 223.0MB 73%
tours avol1 aggr0 online RW 20MB 2.52MB 87%
tours citrixvol1 aggr1 online RW 20MB 18.89MB 5%
tours dept1_share aggr1 online RW 20MB 18.89MB 5%
tours dept2_share aggr1 online RW 20MB 18.89MB 5%
tours testvol1 aggr0 online RW 20MB 18.89MB 5%
tours tours_root aggr0 online RW 20MB 18.89MB 5%
tours user_share aggr1 online RW 20MB 18.89MB 5%
tours vmwarevol1 aggr1 online RW 20MB 18.89MB 5%
9 entries were displayed.
cdot_mba1::> vol show -fields ?
(volume show)
vserver Vserver Name
volume Volume Name
aggregate Aggregate Name
size Volume Size
dsid Volume Data Set ID
msid Volume Master Data Set ID
state Volume State
type Volume Type
volume-style Volume Style
is-cluster-volume Is Cluster-Mode Volume
is-constituent Is Constituent Volume
policy Export Policy
user User ID
group Group ID
security-style Security Style
unix-permissions UNIX Permissions
junction-path Junction Path
junction-path-source Junction Path Source
junction-active Junction Active
junction-parent Junction Parent Volume
comment Comment
available Available Size
filesystem-size Filesystem Size
total Total User-Visible Size
used Used Size
percent-used Used Percentage
space-nearly-full-threshold-percent Volume Nearly Full Threshold Percent
space-full-threshold-percent Volume Full Threshold Percent
max-autosize Maximum Autosize (for flexvols only)
autosize-increment Autosize Increment (for flexvols only)
min-autosize Minimum Autosize
autosize-grow-threshold-percent Autosize Grow Threshold Percentage
autosize-shrink-threshold-percent Autosize Shrink Threshold Percentage
autosize-mode Autosize Mode
autosize Autosize Enabled (for flexvols only)
files Total Files (for user-visible data)
files-used Files Used (for user-visible data)
space-guarantee Space Guarantee Style
space-guarantee-enabled Space Guarantee in Effect
snapdir-access Snapshot Directory Access Enabled
percent-snapshot-space Space Reserved for Snapshots
snapshot-space-used Snapshot Reserve Used
snapshot-policy Snapshot Policy
create-time Creation Time
language Language
clone-volume Clone Volume
node Node name
nvfail NVFAIL Option
filesys-size-fixed Is File System Size Fixed
extent-enabled Extent Option
overwrite-reserve Reserved Space for Overwrites
fractional-reserve Fractional Reserve
snapshot-clone-dependency Snapshot Cloning Dependency
space-mgmt-try-first Primary Space Management Strategy
read-realloc Read Reallocation Option
is-inconsistent Inconsistency in the File System
is-quiesced-on-disk Is Volume Quiesced (On-Disk)
is-quiesced-in-memory Is Volume Quiesced (In-Memory)
is-sis-volume Volume Contains Shared or Compressed Data
sis-space-saved Space Saved by Storage Efficiency
sis-space-saved-percent Percentage Saved by Storage Efficiency
dedupe-space-saved Space Saved by Deduplication
dedupe-space-saved-percent Percentage Saved by Deduplication
dedupe-space-shared Space Shared by Deduplication
compression-space-saved Space Saved by Compression
compression-space-saved-percent Percentage Space Saved by Compression
block-type Block Type
flexcache-connection-status FlexCache Connection Status
is-moving Is Volume Moving
hybrid-cache-eligibility Flash Pool Caching Eligibility
hybrid-cache-write-caching-ineligibility-reason Flash Pool Write Caching Ineligibility Reason
is-managed-by-service Managed By Storage Service
enable-snapdiff Create Namespace Mirror Constituents For SnapDiff Use
constituent-role Constituent Volume Role
qos-policy-group QoS Policy Group Name
is-volume-in-cutover Is Volume Move in Cutover Phase
snapshot-count Number of Snapshot Copies in the Volume
There are obviously a lot of different fields that we could display depending on the use case.
Perhaps we actually want to display fewer fields, not more:
cdot_mba1::> vol show -fields vserver,volume,aggregate,size,percent-used
(volume show)
vserver volume aggregate size percent-used
------------ ------ --------- ------- ------------
cdot_mba1-01 vol0 aggr0 851.5MB 73%
tours avol1 aggr0 20MB 87%
tours citrixvol1
aggr1 20MB 5%
tours dept1_share
aggr1 20MB 5%
tours dept2_share
aggr1 20MB 5%
tours testvol1
aggr0 20MB 5%
tours tours_root
aggr0 20MB 5%
tours user_share
aggr1 20MB 5%
tours vmwarevol1
aggr1 20MB 5%
9 entries were displayed.
Perhaps we want to look at information more relevant to a NAS configuration:
cdot_mba1::> vol show -fields vserver,volume,security-style,junction-path,language,user,group,policy,unix-permissions
(volume show)
vserver volume policy user group security-style unix-permissions junction-path language
------------ ------ ------ ---- ----- -------------- ---------------- ------------- --------
cdot_mba1-01 vol0 - - - - ------------ - -
tours avol1 default
0 0 unix ---rwxr-xr-x - C.UTF-8
tours citrixvol1
default
0 0 unix ---rwxr-xr-x - C.UTF-8
tours dept1_share
default
0 0 unix ---rwxr-xr-x - C.UTF-8
tours dept2_share
default
0 0 unix ---rwxr-xr-x - C.UTF-8
tours testvol1
default
0 0 unix ---rwxr-xr-x - C.UTF-8
tours tours_root
default
0 0 unix ---rwxr-xr-x / C.UTF-8
tours user_share
default
0 0 unix ---rwxr-xr-x - C.UTF-8
tours vmwarevol1
default
0 0 unix ---rwxr-xr-x - C.UTF-8
9 entries were displayed.
One subtle thing to notice: fields are not displayed in the order in which you list them. The display order is not configurable by the user.
Field Filtering
The tab completion functionality of the cluster shell lends itself to filtering based on field just by its operation. As you tab through the parameters of a command you are continuously filtering out possible options through your choices. While this is explicit in a create or modify command, it’s equally true for displaying information.
cdot_mba1::> vol show -vserver
cdot_mba1 cdot_mba1-01 tours
cdot_mba1::> vol show -vserver tours
(volume show)
Vserver Volume Aggregate State Type Size Available Used%
--------- ------------ ------------ ---------- ---- ---------- ---------- -----
tours avol1 aggr0 online RW 20MB 2.52MB 87%
tours citrixvol1 aggr1 online RW 20MB 18.89MB 5%
tours dept1_share aggr1 online RW 20MB 18.89MB 5%
tours dept2_share aggr1 online RW 20MB 18.89MB 5%
tours testvol1 aggr0 online RW 20MB 18.89MB 5%
tours tours_root aggr0 online RW 20MB 18.89MB 5%
tours user_share aggr1 online RW 20MB 18.89MB 5%
tours vmwarevol1 aggr1 online RW 20MB 18.89MB 5%
8 entries were displayed.
Here, I’ve used [TAB] to first show me the possible values for that field, and then to filter the results based on my choice of “tours”.
I can also filter just by specifying which values I’m interested in. Perhaps I only want to see volumes owned by “tours” that are on aggr0:
cdot_mba1::> vol show -vserver tours -aggregate aggr0 (volume show) Vserver Volume Aggregate State Type Size Available Used% --------- ------------ ------------ ---------- ---- ---------- ---------- ----- tours avol1 aggr0 online RW 20MB 2.50MB 87% tours testvol1 aggr0 online RW 20MB 18.88MB 5% tours tours_root aggr0 online RW 20MB 18.88MB 5% 3 entries were displayed.
I can filter on this further by specifying fields that aren’t even displayed in the output, such as snapshot-count:
cdot_mba1::> vol show -vserver tours -aggregate aggr0 -snapshot-count 3 (volume show) Vserver Volume Aggregate State Type Size Available Used% --------- ------------ ------------ ---------- ---- ---------- ---------- ----- tours avol1 aggr0 online RW 20MB 2.50MB 87% tours testvol1 aggr0 online RW 20MB 18.88MB 5% 2 entries were displayed.
I can then take this and limit which fields are displayed so that I get exactly the data I’m looking for and nothing else:
cdot_mba1::> vol show -vserver tours -aggregate aggr0 -snapshot-count 3 -fields vserver,volume (volume show) vserver volume ------- ------ tours avol1 tours testvol1 2 entries were displayed.
Queries and Operators
Since Data ONTAP is a Unix-like operating system, it’s been a common request that the CLI should support the use of typical Unix wildcard characters and patterns to provide more flexibility for the administrator – and with clustered Data ONTAP the cluster shell does. These patterns are considered to be “queries” and each wildcard or pattern is considered an “operator.” Using queries, administrators are able to more precisely specify the contents of the output for which they’re looking.
The following table is adapted from the one included in the System Administration Guide for clustered Data ONTAP. You’ll notice that most of the listed operators are the standard wildcards used in many systems.
| Operator | Description |
|---|---|
| * | ALL operator: match all values |
| ! | NOT operator: do not match the specified value |
| | (pipe) | OR operator: the pipe symbol acts as a separator between multiple patterns |
| .. | RANGE operator: match any value within the range |
| < | LESS THAN operator: match any value less than the specified one |
| > | GREATER THAN operator: match any value more than the specified one |
| <= | LESS-THAN-OR-EQUAL-TO operator: match any value equal to or less than the specified one |
| >= | GREATER-THAN-OR-EQUAL-TO operator: match any value equal to or more than the specified one |
Let’s provide some examples of each one:
ALL
cdot_mba1::> volume show -volume *
Vserver Volume Aggregate State Type Size Available Used%
--------- ------------ ------------ ---------- ---- ---------- ---------- -----
cdot_mba1-01
vol0 aggr0 online RW 851.5MB 243.5MB 71%
tours avol1 aggr0 online RW 20MB 2.66MB 86%
tours citrixvol1 aggr1 online RW 20MB 18.89MB 5%
tours dept1_share aggr1 online RW 20MB 18.89MB 5%
tours dept2_share aggr1 online RW 20MB 18.89MB 5%
tours testvol1 aggr0 online RW 20MB 18.89MB 5%
tours tours_root aggr0 online RW 20MB 18.89MB 5%
tours user_share aggr1 online RW 20MB 18.89MB 5%
tours vmwarevol1 aggr1 online RW 20MB 18.89MB 5%
9 entries were displayed.
The ALL operator can be used with partial values regardless of placement within that value:
cdot_mba1::> volume show -volume *vol1 Vserver Volume Aggregate State Type Size Available Used% --------- ------------ ------------ ---------- ---- ---------- ---------- ----- tours avol1 aggr0 online RW 20MB 2.66MB 86% tours citrixvol1 aggr1 online RW 20MB 18.89MB 5% tours testvol1 aggr0 online RW 20MB 18.89MB 5% tours vmwarevol1 aggr1 online RW 20MB 18.89MB 5% 4 entries were displayed. cdot_mba1::> vol show -volume dept*_share (volume show) Vserver Volume Aggregate State Type Size Available Used% --------- ------------ ------------ ---------- ---- ---------- ---------- ----- tours dept1_share aggr1 online RW 20MB 18.89MB 5% tours dept2_share aggr1 online RW 20MB 18.89MB 5% 2 entries were displayed.
With this flexibility, you can filter and match on more than one value in a specified field, and not just literally all values.
NOT
cdot_mba1::> vol show -volume !vol0 (volume show) Vserver Volume Aggregate State Type Size Available Used% --------- ------------ ------------ ---------- ---- ---------- ---------- ----- tours avol1 aggr0 online RW 20MB 2.66MB 86% tours citrixvol1 aggr1 online RW 20MB 18.89MB 5% tours dept1_share aggr1 online RW 20MB 18.89MB 5% tours dept2_share aggr1 online RW 20MB 18.89MB 5% tours testvol1 aggr0 online RW 20MB 18.89MB 5% tours tours_root aggr0 online RW 20MB 18.89MB 5% tours user_share aggr1 online RW 20MB 18.89MB 5% tours vmwarevol1 aggr1 online RW 20MB 18.89MB 5% 8 entries were displayed.
In this example, there was a single volume we wanted to exclude from the output, but what if we wanted to exclude more than one? Just combine operators:
cdot_mba1::> volume show -volume !*vol1
Vserver Volume Aggregate State Type Size Available Used%
--------- ------------ ------------ ---------- ---- ---------- ---------- -----
cdot_mba1-01
vol0 aggr0 online RW 851.5MB 237.0MB 72%
tours dept1_share aggr1 online RW 20MB 18.89MB 5%
tours dept2_share aggr1 online RW 20MB 18.89MB 5%
tours tours_root aggr0 online RW 20MB 18.89MB 5%
tours user_share aggr1 online RW 20MB 18.89MB 5%
5 entries were displayed.
OR
cdot_mba1::> vol show -volume citrix* | vmware* (volume show) Vserver Volume Aggregate State Type Size Available Used% --------- ------------ ------------ ---------- ---- ---------- ---------- ----- tours citrixvol1 aggr1 online RW 20MB 18.89MB 5% tours vmwarevol1 aggr1 online RW 20MB 18.89MB 5% 2 entries were displayed.
RANGE
Unsurprisingly, we can’t use operators like RANGE, LESS THAN, GREATER THAN, etc. on free-text fields like volume names. Continuing with our examples, let’s start filtering based on the “-percent-used” field and find our most under-utilized volumes:
cdot_mba1::> vol show -percent-used 1..10 (volume show) Vserver Volume Aggregate State Type Size Available Used% --------- ------------ ------------ ---------- ---- ---------- ---------- ----- tours citrixvol1 aggr1 online RW 20MB 18.88MB 5% tours dept1_share aggr1 online RW 20MB 18.88MB 5% tours dept2_share aggr1 online RW 20MB 18.88MB 5% tours testvol1 aggr0 online RW 20MB 18.88MB 5% tours tours_root aggr0 online RW 20MB 18.88MB 5% tours user_share aggr1 online RW 20MB 18.88MB 5% tours vmwarevol1 aggr1 online RW 20MB 18.88MB 5% 7 entries were displayed.
We can do a similar search to find volumes of a certain size range:
cdot_mba1::> vol show -size 500M..1000M
(volume show)
Vserver Volume Aggregate State Type Size Available Used%
--------- ------------ ------------ ---------- ---- ---------- ---------- -----
cdot_mba1-01
vol0 aggr0 online RW 851.5MB 227.1MB 73%
Note the “M” in that last example: when using fields that display different units of measurement, you need to specify that unit in your RANGE operation.
cdot_mba1::> vol show -size 500..1000 (volume show) There are no entries matching your query. cdot_mba1::> vol show -size 1024k..30000k (volume show) Vserver Volume Aggregate State Type Size Available Used% --------- ------------ ------------ ---------- ---- ---------- ---------- ----- tours avol1 aggr0 online RW 20MB 2.56MB 87% tours citrixvol1 aggr1 online RW 20MB 18.88MB 5% tours dept1_share aggr1 online RW 20MB 18.88MB 5% tours dept2_share aggr1 online RW 20MB 18.88MB 5% tours testvol1 aggr0 online RW 20MB 18.88MB 5% tours tours_root aggr0 online RW 20MB 18.88MB 5% tours user_share aggr1 online RW 20MB 18.88MB 5% tours vmwarevol1 aggr1 online RW 20MB 18.88MB 5% 8 entries were displayed.
Let’s try to get the same information as above, but using LESS THAN or MORE THAN instead of a RANGE operation.
LESS THAN
cdot_mba1::> vol show -percent-used <10 (volume show) Vserver Volume Aggregate State Type Size Available Used% --------- ------------ ------------ ---------- ---- ---------- ---------- ----- tours citrixvol1 aggr1 online RW 20MB 18.89MB 5% tours dept1_share aggr1 online RW 20MB 18.89MB 5% tours dept2_share aggr1 online RW 20MB 18.89MB 5% tours testvol1 aggr0 online RW 20MB 18.89MB 5% tours tours_root aggr0 online RW 20MB 18.88MB 5% tours user_share aggr1 online RW 20MB 18.89MB 5% tours vmwarevol1 aggr1 online RW 20MB 18.89MB 5% 7 entries were displayed.
GREATER THAN
cdot_mba1::> vol show -size >500M
(volume show)
Vserver Volume Aggregate State Type Size Available Used%
--------- ------------ ------------ ---------- ---- ---------- ---------- -----
cdot_mba1-01
vol0 aggr0 online RW 851.5MB 225.6MB 73%
LESS-THAN-OR-EQUAL-TO
cdot_mba1::> vol show -size <=20M (volume show) Vserver Volume Aggregate State Type Size Available Used% --------- ------------ ------------ ---------- ---- ---------- ---------- ----- tours avol1 aggr0 online RW 20MB 2.46MB 87% tours citrixvol1 aggr1 online RW 20MB 18.89MB 5% tours dept1_share aggr1 online RW 20MB 18.89MB 5% tours dept2_share aggr1 online RW 20MB 18.89MB 5% tours testvol1 aggr0 online RW 20MB 18.89MB 5% tours tours_root aggr0 online RW 20MB 18.89MB 5% tours user_share aggr1 online RW 20MB 18.89MB 5% tours vmwarevol1 aggr1 online RW 20MB 18.89MB 5% 8 entries were displayed.
To demonstrate that this is really being evaluated differently than just LESS THAN:
cdot_mba1::> vol show -size <20M (volume show) There are no entries matching your query.
GREATER-THAN-OR-EQUAL-TO
cdot_mba1::> vol show -size >=20M
(volume show)
Vserver Volume Aggregate State Type Size Available Used%
--------- ------------ ------------ ---------- ---- ---------- ---------- -----
cdot_mba1-01
vol0 aggr0 online RW 851.5MB 224.3MB 73%
tours avol1 aggr0 online RW 20MB 2.52MB 87%
tours citrixvol1 aggr1 online RW 20MB 18.89MB 5%
tours dept1_share aggr1 online RW 20MB 18.89MB 5%
tours dept2_share aggr1 online RW 20MB 18.89MB 5%
tours testvol1 aggr0 online RW 20MB 18.89MB 5%
tours tours_root aggr0 online RW 20MB 18.89MB 5%
tours user_share aggr1 online RW 20MB 18.89MB 5%
tours vmwarevol1 aggr1 online RW 20MB 18.89MB 5%
9 entries were displayed.
Putting It All Together
Even though these examples are rather trivial, the filtering and querying capabilities in the CLI can be very powerful when they are combined.
For example, what if I want to find all volumes which are more than 50% utilized with a certain minimum number of snapshots – except for those belonging to a particular SVM or on a particular aggregate?
cdot_mba1::> vol show -volume * -vserver !cdot_mba1-01 -aggregate !aggr1 -percent-used >50 -snapshot-count >=3 (volume show) Vserver Volume Aggregate State Type Size Available Used% --------- ------------ ------------ ---------- ---- ---------- ---------- ----- tours avol1 aggr0 online RW 20MB 2.45MB 87%
As you can see, you can run very detailed queries that are still simple to construct and easy to understand.
In even moderately sized environments, effective use of the capabilities within the clustered Data ONTAP shell can provide significant administrator efficiencies.
Next up: Extended queries.
4 thoughts on “Tours of the Black Prompt: Clustered NetApp Data ONTAP – Part 3”