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
Pingback: Installing dbatools – Curated SQL
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
Awesome tips, thanks so much, Patrick!
Thanks Patrick – this helped me greatly when installing behind a proxy!! 🙂
Pingback: Je suis DBA, Powershell est mon ami! |
Pingback: Installing dbachecks – dbatools
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 !
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.
That’d be a good blog post, i’ll put it on my list then add an addendum to this post. What you’ll likely want to do is `Get-Process *powershel* | Stop-Process` then try updating after reopening.
Not working that ways. It’s a bit deeper than that:
https://stackoverflow.com/a/54563398
How to add the server inventory $servers ?