NetAppDocs-Lite PowerShell Module

Frequently Asked Questions


Why do I need to modify the PowerShell Execution Policy?

By default, the PowerShell Execution Policy is set to 'Restricted'. This means that no scripts can be run and that PowerShell can be used only in interactive mode. These scripts are digitally signed so the policy can be set to either 'Unrestricted', 'RemoteSigned' or 'Allsigned'.

Why does it seem like nothing is happening when I invoke the scripts (no status output shown)?

By default, no status output is written to the screen. As this is a PowerShell module, the best practice is not to use Write-Host for status. My plan, moving forward, is to include a GUI front end for this module that will provide that status output. But, in the meantime, you can specify a -Verbose to all of the functions and you will see detailed status information.

For example:

PS> Get-NtapClusterData -Name cluster1 -Verbose

Alternatively, within your PowerShell session you can just set the $VerbosePreference to 'Continue' and this will turn on -Verbose for every command invoked within that session.

PS> $VerbosePreference = 'Continue'

I just got a warning message when I imported the module that stated "It has been at least 14 days since a check was performed for updates. Please run the function Show-NtapDocsUpdate to perform the update checks." What does this mean?

NetAppDocs v4.1.0 added support for update notifications using the Show-NtapDocsUpdate function. This function will query the update server to check if there are any new versions of the module available as well as if there are any updated module/resource files. By default, this warning message will remind you every 14 days to check for updates. There is a corresponding Update-NtapDocsFiles function that will download the updated module/resource files. Any updates to the module version itself must be downloaded from the NetApp Tools site. This notification can be disabled by setting a variable in your PowerShell profile:

Set-Variable -Name NetAppDocs_DisableUpdateNotification -Value 1 -Scope Global

Using Windows 10, I am unable to connect to a Data ONTAP 7-Mode storage system using HTTPS. What is the issue?

By default, the key length used when generating SSL certificates using 'secureadmin setup ssl' in 7-Mode is 512 bits. Windows 10 no longer accepts a certificate with this key length so the HTTPS connection fails. If using HTTP is not possible, then you must generate a new certificate using a key length of at least 1024 bits. This shouldn't affect ONTAP, since the default key length in cDOT is 2048 bits. However, it is possible to generate a 512 bit key in cDOT so this same issue could be encountered.

I just got an error on the screen stating that 'An unexpected error occurred...' and then the execution was halted. What do I do now?

We added some error handling within the code to catch any errors that are outside the NetApp ONTAP PowerShell Toolkit errors or any problems with the systems themselves (those types of errors are handled specifically and, hopefully, gracefully). This typically shows up when we are performing an action and the value is null or empty. An error is thrown and the script is terminated. These are, most definitely, unexpected errors and we would very much appreciate you sending an email to the support staff. Usually the fix is simple and the error message should be descriptive enough to help me identify the issue, but only if we hear about it!

What are the minimum rights necessary to collect data from an ONTAP storage system?

Answer: If the admin user (or a user with the role of admin) is not available for use within the environment, a more restricted user and role can be created using the below commands. For ONTAP systems, you may also use the 'domain' authentication method (using a properly set up CIFS domain-tunnel) and create the 'ssh' application instead of the 'console' application ('console' is still preferred as it is not as susceptible to timeout issues).

ONTAP CLI:

security login role create -role netappdocsrole -vserver <ClusterName> -cmddirname DEFAULT -access readonly
security login role create -role netappdocsrole -vserver <ClusterName> -cmddirname set -access all
security login role create -role netappdocsrole -vserver <ClusterName> -cmddirname "system node run" -access all
security login create -user-or-group-name netappdocs -vserver <ClusterName> -authentication-method password -role netappdocsrole -application ontapi
security login create -user-or-group-name netappdocs -vserver <ClusterName> -authentication-method password -role netappdocsrole -application console
security login password -vserver <ClusterName> -username netappdocs

ONTAP PowerShell:

New-NcRole -Role netappdocsrole -Vserver <ClusterName> -CommandDirectory DEFAULT -AccessLevel readonly
New-NcRole -Role netappdocsrole -Vserver <ClusterName> -CommandDirectory set -AccessLevel all
New-NcRole -Role netappdocsrole -Vserver <ClusterName> -CommandDirectory 'system node run' -AccessLevel all
New-NcUser -UserName netappdocs -Vserver <ClusterName> -AuthMethod password -Role netappdocsrole -Application ontapi
New-NcUser -UserName netappdocs -Vserver <ClusterName> -AuthMethod password -Role netappdocsrole -Application console
Set-NcUserPassword -UserName netappdocs -VserverContext <ClusterName> -Password <password>

7-Mode CLI:

useradmin role add netappdocsrole -a login-http-admin,api-*,cli-*,security-api-vfiler,security-priv-advanced
useradmin group add netappdocsgroup -r netappdocsrole
useradmin user add netappdocs -g netappdocsgroup

7-Mode PowerShell:

New-NaRole -Role netappdocsrole -Capabilities login-http-admin,api-*,cli-*,security-api-vfiler,security-priv-advanced
New-NaGroup -Group netappdocsgroup -Roles netappdocsrole
New-NaUser -User netappdocs -Groups netappdocsgroup -Password <Password>

What is the purpose of the -Terse parameter on the Format-Ntap*Data functions?

Answer: There are a number of tables known to take a large amount of time to process. This is typically due to large quantities of rows in the tables (Snapshots, CIFS shares, etc). The -Terse switch parameter excludes these tables to speed up the processing.

If you need to include one or more of these pre-defined tables but continue to exclude the others, you must not use the -Terse switch parameter. Instead, use the -ExcludeTable parameter with the comma-separated list of table names to exclude.

You can exclude additional tables by combining the -Terse switch with the -ExcludeTable parameter.

The following table shows the default table names that will be excluded from processing when using the -Terse switch parameter.

System Type Table Names
ONTAP AutosupportTriggers, CifsShareAcls, CifsShares, DriveDetails, ExportPolicyRules, PartitionDetails, QtreeConfiguration, QuotaPolicyRules, SvmAdministrativeRoles, VolumeSnapshotDetails
ONTAP ASUP AutosupportTriggers, CifsShareAcls, CifsShares, DriveDetails, ExportPolicyRules, PartitionDetails, QtreeConfiguration, QuotaPolicyRules, VolumeSnapshotDetails
SVM CifsShareAcls, CifsShares, ExportPolicyRules, QtreeConfiguration, QuotaPolicyRules, SvmAdministrativeRoles, VolumeSnapshotDetails
SVM ASUP CifsShareAcls, CifsShares, ExportPolicyRules, QtreeConfiguration, QuotaPolicyRules, VolumeSnapshotDetails
7-Mode CifsShareAcls, CifsShares, DriveDetails, NfsExportRules, QtreeConfiguration, QuotaConfiguration
7-Mode ASUP CifsShareAcls, CifsShares, DriveDetails, NfsExportRules, QtreeConfiguration, QuotaConfiguration

I use the data sanitization functionality and when I generate a differences report I am seeing many more changes than I would expect. What can I do about this?

Answer: In some tables, the columns used to uniquely identify the row is also set to be sanitized (depending on the SanitizeLevel specified). This is necessary for some entities when they don't have a unique UUID that can be used and we have to use the 'Name' property (for instance). Take, for example, a volume named 'MyVolume' (this is just an example as volumes have unique UUID fields and should not fall under this scenario). The data sanitization routines will change 'MyVolume' to a generic 'vol0001' string to mask the actual name. In one run, however, this might be 'vol0001' and in another it might be 'vol2105'. In this case, when the differences report is generated, it will see these as two different volumes and will show both an add and a delete entry for these.

There are two ways to work around this. The first method is to reduce the fields you are sanitizing (by manipulating the -SanitizeLevel). If this isn't possible, however, then the other option is to use the -SanitizeMappingsXmlFile parameter on the Format-Ntap*Data functions. This parameter will save the SecureString to SanitizedString mappings to an XML file. If you specify this parameter each time you generate NetAppDocs data then the volume name 'MyVolume' will get sanitized to the same string each time and will therefore be evaluated to be the same during the differences report generation. If the file already exists then the current mappings will be used, with new entries added as necessary. If the file does not exist then a new file will be created with the current mappings.

Why can't I use the -VisioFile parameter to copy existing Visio drawings to the Word document on MAC/Linux clients?

Answer: This is currently an issue with the library we are leveraging to perform this action. This functionality may be available for MAC/Linux clients as soon as the library is updated and no longer throws errors. And, we are still planning on being able to generate the Visio (cabling) drawings in a future release.


Why is PowerShell version less than 7.2 no longer supported?

Answer: PowerShell 7.2+ is based on .NET 6 and when the Aspose library that is used to generate the MS Office documentation added support for .NET 6, we removed support for 7.0 and 7.1. This may be added back in the future if there is any demand for it. (Note: Windows PowerShell 5.1+ is still supported along with PowerShell 7.2+)