walk-thru: installing modules from the powershell gallery

Before Apple created the App Store and Microsoft created the Microsoft Store, Linux users basked in the glory of how easy it was to install programs or packages from centralized stores using Package Managers and remote repositories.

For years, power users requested a PowerShell version of apt-get and in 2014 Microsoft delivered with the introduction of the PowerShell Gallery and an accompanying module that allowed users to just Install-Module to install new modules, PowerShell’s version of a package.

Installing dbatools from a super fresh Win10 install

It’s easy for PowerShell toolmakers to forget that new users may have questions about ExecutionPolicy and Repositories. If dbatools is the first module you’ve ever installed and used, this guide is intended to help you with all of your install/setup questions and concerns.

In order to emulate what your experience may be like, I spun up a fresh Windows 10 instance in Azure and went through all of the required steps which include addressing:

  • Setting the Execution Policy
  • Explicitly trusting Microsoft’s PowerShell Gallery repository
  • Installing dbatools
  • Explicitly trusting dbatools as a Publisher, before first use

Execution Policy

PowerShell’s ExecutionPolicy is often misunderstood, but basically it’s there for safety not security. So nobody is being slick when set the Execution Policy to Bypass, Microsoft intentionally added that possiblity. Looking for security? Security experts like Matt Graeber recommend Application white listing.

The default Execution Policy is Restricted. Microsoft says this about Restricted:

Does not load configuration files or run scripts. Restricted is the default execution policy.

I haven’t dug around too much, but I it appears that at least one module, PSReadLine, is allowed to run, because the text is still colorful and pretty. Based on this and the fact that Install-Module is allowed to run even in Restricted mode, I assume that all default Microsoft-signed modules are allowed.

dbatools minimum requirement

Most PowerShell books directed at local development suggest you change your ExecutionPolicy to RemoteSigned. RemoteSigned basically means that all scripts and modules not located on your local computer must be signed. It is what most books will tell you to set your ExecutionPolicy to so that you can code locally.

Thanks to CloudDBA‘s generosity, our module is professionally signed using a code signing certificate from DigiCert. This means that you can use our module even if your environment is set to the second most restrictive Execution Policy, AllSigned. AllSigned is probably most popular on restrictive Enterprise networks.

Code:

Set-ExecutionPolicy -Scope CurrentUser AllSigned

OR, more realistically, set your execution policy to RemoteSigned so you can create scripts on your local machine.

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Trusting Microsoft’s default repository

Now that we’ve got the Execution Policy squared away, let’s move on to the PowerShell Gallery.

Following PowerShell’s Security Guiding Principles, Microsoft doesn’t trust its own repository by default. This is in spite of the fact that it’s super safe and all uploads are analyzed for viruses and malicious code.

Now that you know the Gallery is trustworthy, tell your computer to trust it as well (otherwise you’ll be prompted every time.)

Code:

Set-PSRepository -Name PSGallery -InstallationPolicy Trusted

Install dbatools

Now that you trust the PowerShell Gallery, you can install the module, prompt free.

Code:

Install-Module dbatools

dbatools as a Trusted Publisher

I was so excited when we published our first signed version, reversegiraffe but was kind of disappointed that users were required to explicitly trust us as a publisher. I was under the impression that a good code signing cert (which took a lot of work, proof of identity and faxing of documents) was automatically trusted.

Considering Microsoft doesn’t trust its own Gallery by default, this made sense. Go ahead and trust us by forcing an import of the module, then A for Always.

Code:

Import-Module dbatools

Note: dbatools is installed to your $env:PSModulePath so explicit imports are not required at any other point; dbatools will automatically load once you run one of our commands.

What does trusting a publisher do? It places our public key into your Current User’s Trusted Publisher PKI store.

Cool!

Go to town

Now that you’ve set your execution policy, trusted the gallery, installed dbatools, and trusted us as a publisher, you’re set. Just run a command 🤗

Want to see more? dbatools Major Contributor William Durkin of CloudDBA made a video! And it’s not even silent 😉

Thanks for reading,
- Chrissy

11 thoughts on “walk-thru: installing modules from the powershell gallery

  1. Pingback: Installing dbatools – Curated SQL

  2. Patrick Flynn Reply

    One scenario that is not commonly covered is requirement to install Powershell Modules when behind a corporate firewall. This will cause the Install-Module and other such commands from the Gallery to fail.
    After some searching I found the adding the following code to a script before calling the Install-Module was able to resolve this issue

    # Update Modules from Behind a Proxy
    [system.net.webrequest]::defaultwebproxy = new-object system.net.webproxy(‘http://[YourProxyDNS]:[yourProxyPort]’)
    [system.net.webrequest]::defaultwebproxy.credentials = [System.Net.CredentialCache]::DefaultNetworkCredentials
    [system.net.webrequest]::defaultwebproxy.BypassProxyOnLocal = $true

    You may also need to initially run the following to get Install-Module Working

    # May need to be run initially to install necessary packages for Install-Module

    Register-PSRepository -Default

    Install-PackageProvider Nuget –force –verbose
    Install-Module –Name PowerShellGet –Force –Verbose

  3. Pingback: Je suis DBA, Powershell est mon ami! |

  4. Pingback: Installing dbachecks – dbatools

  5. Phil Smith Reply

    When I attempt to trust the repository, it isn’t found.

    PS C:\Windows\system32> Set-PSRepository -Name PSGallery -installationPolicy Trusted
    Set-PSRepository : No repository with the name ‘PSGallery’ was found.
    At line:1 char:1
    + Set-PSRepository -Name PSGallery -installationPolicy Trusted
    + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo : InvalidOperation: (PSGallery:String) [Set-PSRepository], InvalidOperationException
    + FullyQualifiedErrorId : RepositoryNotFound,Set-PSRepository

    Please can you give us some troubleshooting advice ? Very New to using Powershell !

  6. Ed Walsh Reply

    How about updating instructions? I know its, Open Powershell as an Admin and enter:
    Update-Module -name dbatools

    But for those of us that get the dreaded message:
    PS C:\Windows\system32> update-module -name dbatools
    WARNING: The version ‘0.9.411’ of module ‘dbatools’ is currently in use. Retry the operation after closing the applications.

    And you have no application open and have closed and restarted PS to no success.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.