NetAppDocs 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

I just got a warning when I imported the module that stated the "Hardware-ONTAP.xml file is out of date." What does this mean?

The Hardware-ONTAP.xml file contains the latest OS and firmware versions for the hardware components such as controllers, shelves and disks. This file gets generated whenever a new version of the NetAppDocs package is released or at least once a month. As of NetAppDocs v4.1.0, you can use the Update-NtapDocsFiles function to auto-update this and other module files. You can also download the latest file from the NetAppDocs community site and overwrite the existing file located in the Resources folder underneath the NetAppDocs installation folder.

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 a warning that said the version of NetAppDocs being used to generate the documentation is older than the version used to collect the data from the systems. Why is this a problem Or, I'm sure I'm using the same versions but it tells me that I am not. How can this be possible?

Between releases, I may add to or modify the object that is created when the data is gathered off of the systems. I try my best to be backwards compatible with previous changes but when I change the structure during the data gathering then older versions may not be able to parse that data properly, hence the warning message.

If you are certain you have the same versions installed, then it may be that you have another copy of an older release somewhere else in your path that is getting imported instead of the release that you intend to be using. To identify which version is importing and where it is installed, run the following:

PS> Import-Module -Name NetAppDocs
PS> (Get-Module -Name NetAppDocs).Version
PS> (Get-Module -Name NetAppDocs).ModuleBase

If the version is outdated, you can remove it from the path shown and start over with a fresh PowerShell session.

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!

I just got a warning message stating 'Empty DataSet found so document generation not possible'.

This indicates that an issue was encountered either during the data collection or during the formatting of the data. We try to capture and display any errors that would result in no data being processed. If no error was not presented on the screen it may be containined within the $Error variable. You can see the contents of this variable by simply running:

PS> $Error

If it is still unclear as to what the issue is you can contact us using the community site or the e-mail address to help troubleshoot. We will most likely want the screen shot of the -Verbose output as well as any error messages.

I just got a warning message stating 'document parameters were not specified'. What does this mean?

The Out-NtapDocument function accepts four parameters (CustomerName, CustomerLocation, ProjectName and AuthorName) that, when specified, will be shown on the cover page of the output document (Excel or Word output). If you omit these parameters, the default values will be present on the cover page and should remind you to manually fill those in. However, the proper method for manually updating these values will depend on which type of document (Excel or Word). The preferred way to update these documents is to simply use the Update-NtapDocument function with the appropriate parameters.

  • Word Document

    To update the Word document you must modify the custom document properties (Author: File -> Properties -> Advanced Properties / Others: File -> Properties -> Advanced Properties -> Custom). Once updated, highlight the four relevant lines on the cover page and press the 'F9' key.

  • Excel Document

    Since it is not possible to use the document properties in the Excel document itself (without using VBA code), you must modify the value directly in the cover page (replace the ' <Customer Name>' text, for example). You may also update the document property the same way you modify it in Word. However, this is only set in the Excel document for consistency with the Word document and you'll still have to update the cover page directly.

When trying to generate a differences report with the Compare-NtapDocsData function I get an error stating that the DataSets need to be formatted using at least v3.2.0 of NetAppDocs. What does this mean?

During development for v3.2.0, many changes were made to the DataSet schemas that have made generating differences reports against the older versions difficult. We had to make the decision to no longer support any formatted data prior to v3.2.0. We do apologize for this inconvenience and in an upcoming release we will be making the necessary changes in the difference report generation code to allow for processing data from different NetAppDocs versions (still v3.2.0+ though).

Please send us a quick email to NetAppDocs Support and let us know that you have been affected by this scenario. We have not seen significant adoption of this feature and are unsure how often a difference report is generated over greater periods of time.

Is there really nothing I can do to get this differences report generated?

If you still have the raw files used to generate the earlier formatted data, you can use the latest NetAppDocs version to format those files again and generate an updated formatted XML file. We added a new -ForceOrder parameter to the Compare-NtapDocsData function for this scenario (where the 'older' data was formatted after the most recent data was formatted). This -ForceOrderparameter would be necessary since, by default, the function uses the timestamps the data was formatted to identify the oldest and the newest formatted DataSets. In this scenario, the older DataSet would have the later timestamp and so the Compare-NtapDocsData function would sort them incorrectly. You specify the oldest DataSet using the -DataSet1 parameter, the newest DataSet using the -DataSet2 parameter and the -ForceOrder parameter will force the sort order properly.

During the Format function, I get a warning stating "A null value was not expected (table: 'TableName')" or "A duplicate row was not expected (table: 'TableName')". What does this mean?

When adding support for differences reports (the Compare-NtapDocsData function) each table needed to have unique ID columns added. These are typically 'UUID' fields. Once these columns are set as PrimaryKeys for the table, the value for these columns can not be null and there should not be any duplicate rows. This warning means that, for whatever reason, a value for a column defined as a PrimaryKey was null or that even with the PrimaryKeys defined there was a duplicate row added to the table. To make sure that the data is still present in the table we remove the PrimaryKeys and if the value was null then we set this column to AllowDbNull. The only effect this has on the table is when the data is used as input to the Compare-NtapDocsData function for generating a differences report in the future then this table will be excluded from those differences calculations.

As the warning message suggests, please contact us to let us know that you have run into this scenario. In some cases, we have to calculate these UUID fields and knowing about these errors will help us code these calculations more accurately.

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 will 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+)