30 November 2014

XtremIO.Utils PowerShell Module General Info

XtremIO + PowerShell!Herein lies much of the supporting/side information about this PowerShell module that has been written throughout the related vNugglets posts.  The intention, however, is to create this more central spot for this info, instead of people having to sift through the previous posts to get all of these tidbits. To read about the latest additions and changes, one can refer to the change log and the ReadMe (which are available in the module itself, too).
* Update 15 Nov 2015:
Updated links to changelog and readme to be to GitHub, as well as the link to the PowerShell module itself
* end of 15 Nov 2015 update

Module availability:

One can get the XtremIO.Utils module in a couple of ways:
  • via the supercool module PsGet, so installing/updating the module becomes a snap for PsGet module users.  The quick how-to on using PsGet to install the XtremIO.Utils module:
    PS vN:\> Install-Module -Verbose -Module XtremIO.Utils
    
    
    Or, to update the existing version you may already have:
    PS vN:\> Update-Module -Verbose -Module XtremIO.Utils
    
    
  • Or, if you like the "old fashioned" module management route (of manually handling the module grab), you can always follow the steps:
    1. download from latest and greatest! https://github.com/mtboren/XtremIO.Utils/releases/download/Latest/XtremIO.Utils.zip
    2. unzip somewhere you like (like, say, in Join-Path ${env:\userprofile} "Documents\WindowsPowerShell\Modules")
    3. you should now have a folder named <pathToModules>\XtremIO.Utils, in which the PowerShell files reside (see note below about using Unblock-File, since this module is not yet Authenticode signed)
    4. Import-Module <pathToModules>\XtremIO.Utils

Unblock-File discussion:

One of the other "features" of this module:  we have not yet set the Authenticode signature for it.  That is, it is unsigned.  We went back and forth on the solution:
  • buy a legit cert for code signing (best solution, but $$$)
  • sign it with a self-signed cert (which still leads to a prompt of 'Do you want to run software from this untrusted publisher?' when you try to import the module, since everyone is security-minded and has at least the RemoteSigned execution policy set on their machines)
  • ✔ do not add a signature, and make mention that you will need to Unblock-File the files in the module (after careful inspection of the files to make sure that there is nothing dangerous in there; but, we're talking about vNugglets, here -- you can trust us, right?!  a:  No.  Trust no one)
So, since we went with the last option there, below is the quick/easy way to unblock files.  But, again, this should only be done when you trust the code in the files that you are unblocking -- inspecting the files is for your own good.  Anyway, the unblock command:
PS vN:\> Get-ChildItem <pathToModules>\XtremIOInfo | Unblock-File


Credentials discussion:

Credentials come into play in a couple of ways in this module.  One can use the New-XIOStoredCred cmdlet to store one credential persistently on disk.  And, the use of the Connect-XIOServer cmdlet holds credentials in a variable, only for the duration of the PowerShell session (and, only while connected to any XIO servers).

Stored credentials are encrypted using the Windows Data Protection API, via a derivative of HalR9000's Export-PSCredential.  If the encrypted credential file is found at runtime of any of the module's functions that require credentials, the credentials will be imported from said file transparently.

Decryption of the encrypted credentials can only be performed by the user account that performed the encryption, and on the same computer on which the encryption was performed.  This module stores the credential file in the ${env:temp} directory by default, and this location is configurable as desired.

If no credentials are specified to the functions of this module, the given function will look for the credential file in the configured location.  If none exists, the functions behave as before:  they will prompt for credentials as necessary.  And, you can get the stored credential with Get-XIOStoredCred, and remove it from disk, if you would like, with Remove-XIOStoredCred.

No comments:

Post a Comment