2017-03-28 01:44:28 +02:00
# Package Installation Instructions
2016-06-17 01:38:57 +02:00
2017-03-28 01:44:28 +02:00
## MSI
2017-05-02 19:14:17 +02:00
To install PowerShell on Windows Full SKU (works on Windows 7 SP1 and later), download either the MSI from [AppVeyor][] for a nightly build,
2018-01-19 00:07:43 +01:00
or a released package from our GitHub [releases][] page.
2016-07-27 20:11:29 +02:00
2016-07-17 15:37:33 +02:00
Once downloaded, double-click the installer and follow the prompts.
2016-06-17 01:38:57 +02:00
2016-08-01 23:03:51 +02:00
There is a shortcut placed in the Start Menu upon installation.
2017-03-28 01:44:28 +02:00
* By default the package is installed to `$env:ProgramFiles\PowerShell\`
2018-03-01 20:54:25 +01:00
* You can launch PowerShell via the Start Menu or `pwsh` from a new command prompt.
2017-05-02 19:14:17 +02:00
### Prerequisites
2017-10-11 01:40:07 +02:00
To enable PowerShell remoting over WinRM, the following prerequisites need to be met:
2017-08-18 21:47:43 +02:00
* Install the [Universal C Runtime ](https://www.microsoft.com/download/details.aspx?id=50410 ) on Windows versions prior to Windows 10.
2017-05-02 19:14:17 +02:00
It is available via direct download or Windows Update.
Fully patched (including optional packages), supported systems will already have this installed.
2017-10-11 01:40:07 +02:00
* Install the Windows Management Framework (WMF) [4.0 ](https://www.microsoft.com/download/details.aspx?id=40855 )
or newer ([5.0](https://www.microsoft.com/download/details.aspx?id=50395),
[5.1 ](https://www.microsoft.com/download/details.aspx?id=54616 )) on Windows 7.
2016-08-17 20:54:48 +02:00
2017-10-24 20:13:17 +02:00
## ZIP
PowerShell binary ZIP archives are provided to enable advanced deployment scenarios.
Be noted that when using the ZIP archive, you won't get the prerequisites check as in the MSI package.
So in order for remoting over WinRM to work properly on Windows versions prior to Windows 10,
you need to make sure the [prerequisites ](#prerequisites ) are met.
2017-12-15 23:05:20 +01:00
## Deploying on Windows IoT
Windows IoT already comes with Windows PowerShell which we will use to deploy PowerShell Core 6.
* Create `PSSession` to target device
```powershell
$s = New-PSSession -ComputerName < deviceIp > -Credential Administrator
```
* Copy the zip package to the device
```powershell
# change the destination to however you had partitioned it with sufficient space for the zip and the unzipped contents
# the path should be local to the device
2018-03-19 19:38:27 +01:00
Copy-Item .\PowerShell-6.0.2-win-arm32.zip -Destination u:\users\administrator\Downloads -ToSession $s
2017-12-15 23:05:20 +01:00
```
* Connect to the device and expand the archive
```powershell
Enter-PSSession $s
cd u:\users\administrator\downloads
2018-03-19 19:38:27 +01:00
Expand-Archive .\PowerShell-6.0.2-win-arm32.zip
2017-12-15 23:05:20 +01:00
```
* Setup remoting to PowerShell Core 6
```powershell
2018-03-19 19:38:27 +01:00
cd .\PowerShell-6.0.2-win-arm32
2017-12-15 23:05:20 +01:00
# Be sure to use the -PowerShellHome parameter otherwise it'll try to create a new endpoint with Windows PowerShell 5.1
.\Install-PowerShellRemoting.ps1 -PowerShellHome .
# You'll get an error message and will be disconnected from the device because it has to restart WinRM
```
* Connect to PowerShell Core 6 endpoint on device
```powershell
# Be sure to use the -Configuration parameter. If you omit it, you will connect to Windows PowerShell 5.1
2018-03-19 19:38:27 +01:00
Enter-PSSession -ComputerName < deviceIp > -Credential Administrator -Configuration powershell.6.0.2
2017-12-15 23:05:20 +01:00
```
2017-03-28 01:44:28 +02:00
## Deploying on Nano Server
2017-02-25 00:38:29 +01:00
2017-08-18 21:47:43 +02:00
These instructions assume that Windows PowerShell is running on the Nano Server image and that it has been generated by the [Nano Server Image Builder ](https://technet.microsoft.com/windows-server-docs/get-started/deploy-nano-server ).
2017-02-25 00:38:29 +01:00
Nano Server is a "headless" OS and deployment of PowerShell Core binaries can happen in two different ways:
1. Offline - Mount the Nano Server VHD and unzip the contents of the zip file to your chosen location within the mounted image.
2017-03-28 01:44:28 +02:00
1. Online - Transfer the zip file over a PowerShell Session and unzip it in your chosen location.
2017-02-25 00:38:29 +01:00
In both cases, you will need the Windows 10 x64 Zip release package and will need to run the commands within an "Administrator" PowerShell instance.
2017-03-28 01:44:28 +02:00
### Offline Deployment of PowerShell Core
2017-02-25 00:38:29 +01:00
1. Use your favorite zip utility to unzip the package to a directory within the mounted Nano Server image.
2017-03-28 01:44:28 +02:00
1. Unmount the image and boot it.
1. Connect to the inbox instance of Windows PowerShell.
1. Follow the instructions to create a remoting endpoint using the [another instance technique ](#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register ).
2017-02-25 00:38:29 +01:00
2017-03-28 01:44:28 +02:00
### Online Deployment of PowerShell Core
2017-02-25 00:38:29 +01:00
The following steps will guide you through the deployment of PowerShell Core to a running instance of Nano Server and the configuration of its remote endpoint.
* Connect to the inbox instance of Windows PowerShell
2017-03-28 01:44:28 +02:00
2017-02-25 00:38:29 +01:00
```powershell
$session = New-PSSession -ComputerName < Nano Server IP address > -Credential < An Administrator account on the system >
```
2017-03-28 01:44:28 +02:00
2017-02-25 00:38:29 +01:00
* Copy the file to the Nano Server instance
2017-03-28 01:44:28 +02:00
2017-02-25 00:38:29 +01:00
```powershell
2017-09-14 01:37:43 +02:00
Copy-Item < local PS Core download location > \powershell-< version > -win-x64.zip c:\ -ToSession $session
2017-02-25 00:38:29 +01:00
```
2017-03-28 01:44:28 +02:00
2017-02-25 00:38:29 +01:00
* Enter the session
2017-03-28 01:44:28 +02:00
2017-02-25 00:38:29 +01:00
```powershell
Enter-PSSession $session
```
2017-03-28 01:44:28 +02:00
2017-02-25 00:38:29 +01:00
* Extract the Zip file
2017-03-28 01:44:28 +02:00
2017-02-25 00:38:29 +01:00
```powershell
# Insert the appropriate version.
2017-09-14 01:37:43 +02:00
Expand-Archive -Path C:\powershell-< version > -win-x64.zip -DestinationPath "C:\PowerShellCore_< version > "
2017-02-25 00:38:29 +01:00
```
2017-03-28 01:44:28 +02:00
* Follow the instructions to create a remoting endpoint using the [another instance technique ](#executed-by-another-instance-of-powershell-on-behalf-of-the-instance-that-it-will-register ).
## Instructions to Create a Remoting Endpoint
2016-06-17 01:38:57 +02:00
2017-03-28 01:44:28 +02:00
Beginning with 6.0.0-alpha.9, the PowerShell package for Windows includes a WinRM plug-in (pwrshplugin.dll) and an installation script (Install-PowerShellRemoting.ps1).
These files enable PowerShell to accept incoming PowerShell remote connections when its endpoint is specified.
2016-07-27 20:11:29 +02:00
2017-03-28 01:44:28 +02:00
### Motivation
2016-08-17 00:12:33 +02:00
2017-03-28 01:44:28 +02:00
An installation of PowerShell can establish PowerShell sessions to remote computers using `New-PSSession` and `Enter-PSSession` .
To enable it to accept incoming PowerShell remote connections, the user must create a WinRM remoting endpoint.
This is an explicit opt-in scenario where the user runs Install-PowerShellRemoting.ps1 to create the WinRM endpoint.
The installation script is a short-term solution until we add additional functionality to `Enable-PSRemoting` to perform the same action.
2016-08-17 00:12:33 +02:00
For more details, please see issue [#1193 ](https://github.com/PowerShell/PowerShell/issues/1193 ).
2017-03-28 01:44:28 +02:00
### Script Actions
2016-08-17 00:12:33 +02:00
The script
2016-10-28 10:02:32 +02:00
1. Creates a directory for the plug-in within %windir%\System32\PowerShell
2017-03-28 01:44:28 +02:00
1. Copies pwrshplugin.dll to that location
1. Generates a configuration file
1. Registers that plug-in with WinRM
2016-08-17 00:12:33 +02:00
2017-03-28 01:44:28 +02:00
### Registration
2017-02-25 00:38:29 +01:00
2016-08-17 00:12:33 +02:00
The script must be executed within an Administrator-level PowerShell session and runs in two modes.
2017-03-28 01:44:28 +02:00
#### Executed by the instance of PowerShell that it will register
2016-08-17 00:12:33 +02:00
``` powershell
Install-PowerShellRemoting.ps1
2017-02-25 00:38:29 +01:00
```
2017-03-28 01:44:28 +02:00
#### Executed by another instance of PowerShell on behalf of the instance that it will register
2016-08-17 00:12:33 +02:00
``` powershell
2018-02-08 22:52:31 +01:00
< path to powershell > \Install-PowerShellRemoting.ps1 -PowerShellHome "< absolute path to the instance ' s $ PSHOME > "
2016-08-17 00:12:33 +02:00
```
2017-03-28 01:44:28 +02:00
2016-08-17 00:12:33 +02:00
For Example:
2017-03-28 01:44:28 +02:00
2016-08-17 00:12:33 +02:00
``` powershell
2018-03-19 19:38:27 +01:00
& 'C:\Program Files\PowerShell\6.0.2\Install-PowerShellRemoting.ps1' -PowerShellHome 'C:\Program Files\PowerShell\6.0.2\'
2016-08-17 00:12:33 +02:00
```
2017-03-28 01:44:28 +02:00
2017-02-25 00:38:29 +01:00
**NOTE:** The remoting registration script will restart WinRM, so all existing PSRP sessions will terminate immediately after the script is run. If run during a remote session, this will terminate the connection.
2016-08-17 00:12:33 +02:00
## How to Connect to the New Endpoint
Create a PowerShell session to the new PowerShell endpoint by specifying `-ConfigurationName "some endpoint name"` . To connect to the PowerShell instance from the example above, use either:
2017-03-28 01:44:28 +02:00
2016-08-17 00:12:33 +02:00
``` powershell
2018-03-19 19:38:27 +01:00
New-PSSession ... -ConfigurationName "powershell.6.0.2"
Enter-PSSession ... -ConfigurationName "powershell.6.0.2"
2017-03-28 01:44:28 +02:00
```
2016-08-17 00:12:33 +02:00
Note that `New-PSSession` and `Enter-PSSession` invocations that do not specify `-ConfigurationName` will target the default PowerShell endpoint, `microsoft.powershell` .
2017-03-28 01:44:28 +02:00
## Artifact Installation Instructions
2016-03-31 08:29:16 +02:00
2017-08-16 21:07:45 +02:00
We publish an archive with CoreCLR bits on every CI build with [AppVeyor][].
2016-03-31 08:29:16 +02:00
2016-07-20 20:33:30 +02:00
[releases]: https://github.com/PowerShell/PowerShell/releases
[signing]: ../../tools/Sign-Package.ps1
2016-07-17 15:37:33 +02:00
[AppVeyor]: https://ci.appveyor.com/project/PowerShell/powershell
2016-03-31 08:29:16 +02:00
2017-03-28 01:44:28 +02:00
## CoreCLR Artifacts
2016-03-31 08:29:16 +02:00
* Download zip package from **artifacts** tab of the particular build.
2016-07-17 15:37:33 +02:00
* Unblock zip file: right-click in File Explorer -> Properties ->
2016-03-31 08:29:16 +02:00
check 'Unblock' box -> apply
* Extract zip file to `bin` directory
2017-10-24 20:13:17 +02:00
* `./bin/pwsh.exe`