diff --git a/docs/installation/windows.md b/docs/installation/windows.md index feed1c1fb3..9a554d3455 100644 --- a/docs/installation/windows.md +++ b/docs/installation/windows.md @@ -1,7 +1,7 @@ -Package installation instructions +Package Installation Instructions ================================= -###MSI: +# MSI: To install PowerShell on Windows Full SKU (works on Win8 and above - x64 based systems), download either the MSI from [AppVeyor][] for a nightly build, or a released package from our GitHub [releases][] page. The MSI file looks like this - `PowerShell_6.0.0.buildversion.msi` @@ -13,14 +13,54 @@ There is a shortcut placed in the Start Menu upon installation. > > You can launch PowerShell via the Start Menu or `$env:ProgramFiles\PowerShell\powershell.exe` -###APPX/WSA: -Additionally, we provide APPX/WSA packages (that are compatible with Nano Server and works on Win10 x64 and above systems), -but these must be self-signed prior to install. -See the [`Sign-Package.ps1`][signing] script for details. +# Instructions to Create a Remoting Endpoint -When using APPX/WSA, the OS needs to be configured to allow [sideloading apps](https://technet.microsoft.com/en-us/windows/jj874388.aspx) +Beginning with 6.0.0-alpha.9, the PowerShell package for Windows includes a WinRM plugin (pwrshplugin.dll) and an installation script (Install-PowerShellRemoting.ps1). +These files enable PowerShell to accept incoming PowerShell remote connections when its endpoint is specified. -Artifact installation instructions +## Motivation + +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. +For more details, please see issue [#1193](https://github.com/PowerShell/PowerShell/issues/1193). + +## Script Actions + +The script + +1. Creates a directory for the plugin within %windir%\System32\PowerShell +2. Copies pwrshplugin.dll to that location +3. Generates a configuration file +4. Registers that plugin with WinRM + +## Registration +The script must be executed within an Administrator-level PowerShell session and runs in two modes. + +* Executed by the instance of PowerShell that it will register +``` powershell +Install-PowerShellRemoting.ps1 +``` +* Executed by another instance of PowerShell on behalf of the instance that it will register. +``` powershell +\Install-PowerShellRemoting.ps1 -PowerShellHome "" -PowerShellVersion "" +``` +For Example: +``` powershell +C:\Program Files\PowerShell\6.0.0.9\Install-PowerShellRemoting.ps1 -PowerShellHome "C:\Program Files\PowerShell\6.0.0.9\" -PowerShellVersion "6.0.0-alpha.9" +``` + +## 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: +``` powershell +New-PSSession ... -ConfigurationName "powershell.6.0.0-alpha.9" +Enter-PSSession ... -ConfigurationName "powershell.6.0.0-alpha.9" +``` +Note that `New-PSSession` and `Enter-PSSession` invocations that do not specify `-ConfigurationName` will target the default PowerShell endpoint, `microsoft.powershell`. + +Artifact Installation Instructions ================================== We publish an archive with CoreCLR and FullCLR bits on every CI build with [AppVeyor][]. @@ -29,7 +69,7 @@ We publish an archive with CoreCLR and FullCLR bits on every CI build with [AppV [signing]: ../../tools/Sign-Package.ps1 [AppVeyor]: https://ci.appveyor.com/project/PowerShell/powershell -CoreCLR artifacts +CoreCLR Artifacts ================= * Download zip package from **artifacts** tab of the particular build.