From a093a4760a602f6065e9bf8d0e323e48fd58e551 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 18 May 2018 10:43:24 -0700 Subject: [PATCH 1/3] migrating docs to docs repo --- docs/BREAKINGCHANGES.md | 313 --------------- docs/DOCSMIGRATION.md | 20 + docs/KNOWNISSUES.md | 166 -------- docs/installation/linux.md | 731 ----------------------------------- docs/installation/macos.md | 102 ----- docs/installation/windows.md | 194 ---------- 6 files changed, 20 insertions(+), 1506 deletions(-) delete mode 100644 docs/BREAKINGCHANGES.md create mode 100644 docs/DOCSMIGRATION.md delete mode 100644 docs/KNOWNISSUES.md delete mode 100644 docs/installation/linux.md delete mode 100644 docs/installation/macos.md delete mode 100644 docs/installation/windows.md diff --git a/docs/BREAKINGCHANGES.md b/docs/BREAKINGCHANGES.md deleted file mode 100644 index fe3d87b19bf..00000000000 --- a/docs/BREAKINGCHANGES.md +++ /dev/null @@ -1,313 +0,0 @@ -# Breaking Changes for PowerShell 6.0 - -## Features no longer available in PowerShell Core - -### PowerShell Workflow - -[PowerShell Workflow][workflow] is a feature in Windows PowerShell that builds on top of [Windows Workflow Foundation (WF)][workflow-foundation] that enables the creation of robust runbooks for long-running or parallelized tasks. - -Due to the lack of support for Windows Workflow Foundation in .NET Core, -we will not continue to support PowerShell Workflow in PowerShell Core. - -In the future, we would like to enable native parallelism/concurrency in the PowerShell language without the need for PowerShell Workflow. - -[workflow]: https://docs.microsoft.com/powershell/scripting/core-powershell/workflows-guide -[workflow-foundation]: https://docs.microsoft.com/dotnet/framework/windows-workflow-foundation/ - -### Custom snap-ins - -[PowerShell snap-ins][snapin] are a predecessor to PowerShell modules that do not have widespread adoption in the PowerShell community. - -Due to the complexity of supporting snap-ins and their lack of usage in the community, -we no longer support custom snap-ins in PowerShell Core. - -Today, this breaks the `ActiveDirectory` and `DnsClient` modules in Windows and Windows Server. - -[snapin]: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_pssnapins - -### WMI v1 cmdlets - -Due to the complexity of supporting two sets of WMI-based modules, -we removed the WMI v1 cmdlets from PowerShell Core: - -* `Get-WmiObject` -* `Invoke-WmiMethod` -* `Register-WmiEvent` -* `Set-WmiInstance` - -Instead, we recommend that you the use the CIM (aka WMI v2) cmdlets which provide the same functionality with new functionality and a redesigned syntax: - -* `Get-CimAssociatedInstance` -* `Get-CimClass` -* `Get-CimInstance` -* `Get-CimSession` -* `Invoke-CimMethod` -* `New-CimInstance` -* `New-CimSession` -* `New-CimSessionOption` -* `Register-CimIndicationEvent` -* `Remove-CimInstance` -* `Remove-CimSession` -* `Set-CimInstance` - -### Microsoft.PowerShell.LocalAccounts - -Due to the use of unsupported APIs, -`Microsoft.PowerShell.LocalAccounts` has been removed from PowerShell Core until a better solution is found. - -### `*-Counter` cmdlets - -Due to the use of unsupported APIs, -the `*-Counter` has been removed from PowerShell Core until a better solution is found. - -## Engine/language changes - -### Rename `powershell.exe` to `pwsh.exe` [#5101](https://github.com/PowerShell/PowerShell/issues/5101) - -In order to give users a deterministic way to call PowerShell Core on Windows (as opposed to Windows PowerShell), -the PowerShell Core binary was changed to `pwsh.exe` on Windows and `pwsh` on non-Windows platforms. - -The shortened name is also consistent with naming of shells on non-Windows platforms. - -### Don't insert line breaks to output (except for tables) [#5193](https://github.com/PowerShell/PowerShell/issues/5193) - -Previously, output was aligned to the width of the console and line breaks were added at the end width of the console, -meaning the output didn't get reformatted as expected if the terminal was resized. -This change was not applied to tables, as the line breaks are necessary to keep the columns aligned. - -### Skip null-element check for collections with a value-type element type [#5432](https://github.com/PowerShell/PowerShell/issues/5432) - -For the `Mandatory` parameter and `ValidateNotNull` and `ValidateNotNullOrEmpty` attributes, skip the null-element check if the collection's element type is value type. - -### Change `$OutputEncoding` to use `UTF-8 NoBOM` encoding rather than ASCII [#5369](https://github.com/PowerShell/PowerShell/issues/5369) - -The previous encoding, ASCII (7-bit), would result in incorrect alteration of the output in some cases. This change is to make `UTF-8 NoBOM` default, which preserves Unicode output with an encoding supported by most tools and operating systems. - -### Remove `AllScope` from most default aliases [#5268](https://github.com/PowerShell/PowerShell/issues/5268) - -To speed up scope creation, `AllScope` was removed from most default aliases. -`AllScope` was left for a few frequently used aliases where the lookup was faster. - -### `-Verbose` and `-Debug` no longer overrides `$ErrorActionPreference` [#5113](https://github.com/PowerShell/PowerShell/issues/5113) - -Previously, if `-Verbose` or `-Debug` were specified, it overrode the behavior of `$ErrorActionPreference`. -With this change, `-Verbose` and `-Debug` no longer affect the behavior of `$ErrorActionPreference`. - -## Cmdlet changes - -### Invoke-RestMethod doesn't return useful info when no data is returned. [#5320](https://github.com/PowerShell/PowerShell/issues/5320) - -When an API returns just `null`, Invoke-RestMethod was serializing this as the string `"null"` instead of `$null`. This change fixes the logic in `Invoke-RestMethod` to properly serialize a valid single value JSON `null` literal as `$null`. - -### Remove `-ComputerName` from `*-Computer` cmdlets [#5277](https://github.com/PowerShell/PowerShell/issues/5277) - -Due to issues with RPC remoting in CoreFX (particularly on non-Windows platforms) and ensuring a consistent remoting experience in PowerShell, -the `-ComputerName` parameter was removed from the `\*-Computer` cmdlets. -Use `Invoke-Command` instead as the way to execute cmdlets remotely. - -### Remove `-ComputerName` from `*-Service` cmdlets [#5090](https://github.com/PowerShell/PowerShell/issues/5094) - -In order to encourage the consistent use of PSRP, the `-ComputerName` parameter was removed from `*-Service` cmdlets. - -### Fix `Get-Item -LiteralPath a*b` if `a*b` doesn't actually exist to return error [#5197](https://github.com/PowerShell/PowerShell/issues/5197) - -Previously, `-LiteralPath` given a wildcard would treat it the same as `-Path` and if the wildcard found no files, it would silently exit. -Correct behavior should be that `-LiteralPath` is literal so if the file doesn't exist, it should error. -Change is to treat wildcards used with `-Literal` as literal. - -### `Import-Csv` should apply `PSTypeNames` upon import when type information is present in the CSV [#5134](https://github.com/PowerShell/PowerShell/issues/5134) - -Previously, objects exported using `Export-CSV` with `TypeInformation` imported with `ConvertFrom-Csv` were not retaining the type information. -This change adds the type information to `PSTypeNames` member if available from the CSV file. - -### `-NoTypeInformation` should be default on `Export-Csv` [#5131](https://github.com/PowerShell/PowerShell/issues/5131) - -This change was made to address customer feedback on the default behavior of `Export-CSV` to include type information. - -Previously, the cmdlet would output a comment as the first line containing the type name of the object. -The change is to suppress this by default as it's not understood by most tools. -Use `-IncludeTypeInformation` to retain the previous behavior. - -### Web Cmdlets should warn when `-Credential` is sent over unencrypted connections [#5112](https://github.com/PowerShell/PowerShell/issues/5112) - -When using HTTP, content including passwords are sent as clear-text. -This change is to not allow this by default and return an error if credentials are being passed in an insecure manner. -Users can bypass this by using the `-AllowUnencryptedAuthentication` switch. - -## API changes - -### Remove `AddTypeCommandBase` class [#5407](https://github.com/PowerShell/PowerShell/issues/5407) - -The `AddTypeCommandBase` class was removed from `Add-Type` to improve performance. -This class is only used by the Add-Type cmdlet and should not impact users. - -### Unify cmdlets with parameter `-Encoding` to be of type `System.Text.Encoding` [#5080](https://github.com/PowerShell/PowerShell/issues/5080) - -The `-Encoding` value `Byte` has been removed from the filesystem provider cmdlets. -A new parameter, `-AsByteStream`, is now used to specify that a byte stream is required as input or that the output is a stream of bytes. - -### Add better error message for empty and null `-UFormat` parameter [#5055](https://github.com/PowerShell/PowerShell/issues/5055) - -Previously, when passing an empty format string to `-UFormat`, an unhelpful error message would appear. A more descriptive error has been added. - -### Clean up console code [#4995](https://github.com/PowerShell/PowerShell/issues/4995) - -The following features were removed as they are not supported in PowerShell Core, -and there are no plans to add support as they exist for legacy reasons for Windows PowerShell: -`-psconsolefile` switch and code, `-importsystemmodules` switch and code, and font changing code. - -### Removed `RunspaceConfiguration` support [#4942](https://github.com/PowerShell/PowerShell/issues/4942) - -Previously, when creating a PowerShell runspace programmatically using the API you could use the legacy [`RunspaceConfiguration`][runspaceconfig] -or the newer [`InitialSessionState`][iss]. -This change removed support for `RunspaceConfiguration` and only supports `InitialSessionState`. - -[runspaceconfig]: https://docs.microsoft.com/dotnet/api/system.management.automation.runspaces.runspaceconfiguration -[iss]: https://docs.microsoft.com/dotnet/api/system.management.automation.runspaces.initialsessionstate - -### `CommandInvocationIntrinsics.InvokeScript` bind arguments to `$input` instead of `$args` [#4923](https://github.com/PowerShell/PowerShell/issues/4923) - -An incorrect position of a parameter resulted in the args passed as input instead of as args. - -### Remove unsupported `-showwindow` switch from `Get-Help` [#4903](https://github.com/PowerShell/PowerShell/issues/4903) - -`-showwindow` relies on WPF, which is not supported on CoreCLR. - -### Allow * to be used in registry path for `Remove-Item` [#4866](https://github.com/PowerShell/PowerShell/issues/4866) - -Previously, `-LiteralPath` given a wildcard would treat it the same as `-Path` and if the wildcard found no files, it would silently exit. -Correct behavior should be that `-LiteralPath` is literal so if the file doesn't exist, it should error. -Change is to treat wildcards used with `-Literal` as literal. - -### Fix `Set-Service` failing test [#4802](https://github.com/PowerShell/PowerShell/issues/4802) - -Previously, if `New-Service -StartupType foo` was used, `foo` was ignored and the service was created with some default startup type. -This change is to explicitly throw an error for an invalid startup type. - -### Rename `$IsOSX` to `$IsMacOS` [#4700](https://github.com/PowerShell/PowerShell/issues/4700) - -The naming in PowerShell should be consistent with our naming and conform to Apple's use of macOS instead of OSX. -However, for readability and consistently we are staying with Pascal casing. - -### Make error message consistent when invalid script is passed to -File, better error when passed ambiguous argument [#4573](https://github.com/PowerShell/PowerShell/issues/4573) - -Change the exit codes of `pwsh.exe` to align with Unix conventions - -### Removal of `LocalAccount` and cmdlets from `Diagnostics` modules. [#4302](https://github.com/PowerShell/PowerShell/issues/4302) [#4303](https://github.com/PowerShell/PowerShell/issues/4303) - -Due to unsupported APIs, the `LocalAccounts` module and the `Counter` cmdlets in the `Diagnostics` module were removed until a better solution is found. - -### Executing powershell script with bool parameter does not work [#4036](https://github.com/PowerShell/PowerShell/issues/4036) - -Previously, using powershell.exe (now `pwsh.exe`) to execute a PowerShell script using `-File` provided no way to pass $true/$false as parameter values. -Support for $true/$false as parsed values to parameters was added. -Switch values are also supported as currently documented syntax doesn't work. - -### Remove `ClrVersion` property from `$PSVersionTable` [#4027](https://github.com/PowerShell/PowerShell/issues/4027) - -The `ClrVersion` property of `$PSVersionTable` is not useful with CoreCLR, end users should not be using that value to determine compatibility. - -### Change positional parameter for `powershell.exe` from `-Command` to `-File` [#4019](https://github.com/PowerShell/PowerShell/issues/4019) - -Enable shebang use of PowerShell on non-Windows platforms. This means on Unix based systems, -you can make a script executable that would invoke PowerShell automatically rather than explicitly invoking `pwsh`. -This also means that you can now do things like `powershell foo.ps1` or `powershell fooScript` without specifying `-File`. -However, this change now requires that you explicitly specify `-c` or `-Command` when trying to do things like `powershell.exe Get-Command`. - -### Implement Unicode escape parsing [#3958](https://github.com/PowerShell/PowerShell/issues/3958) - -`` `u#### `` or `` `u{####} `` is converted to the corresponding Unicode character. -To output a literal `` `u ``, -escape the backtick: ``` ``u ```. - -### Change `New-ModuleManifest` encoding to `UTF8NoBOM` on non-Windows platforms [#3940](https://github.com/PowerShell/PowerShell/issues/3940) - -Previously, `New-ModuleManifest` creates psd1 manifests in UTF-16 with BOM, creating a problem for Linux tools. -This breaking change changes the encoding of `New-ModuleManifest` to be UTF (no BOM) in non-Windows platforms. - -### Prevent `Get-ChildItem` from recursing into symlinks (#1875). [#3780](https://github.com/PowerShell/PowerShell/issues/3780) - -This change brings `Get-ChildItem` more in line with the Unix `ls -r` and the Windows `dir /s` native commands. -Like the mentioned commands, the cmdlet displays symbolic links to directories found during recursion, -but does not recurse into them. - -### Fix `Get-Content -Delimiter` to not include the delimiter in the returned lines [#3706](https://github.com/PowerShell/PowerShell/issues/3706) - -Previously, the output while using `Get-Content -Delimiter` was inconsistent and inconvenient as it required further processing of the data to remove the delimiter. -This change removes the delimiter in returned lines. - -### Implement Format-Hex in C# [#3320](https://github.com/PowerShell/PowerShell/issues/3320) - -The `-Raw` parameter is now a "no-op" (in that it does nothing). -Going forward all of the output will be displayed with a true representation of numbers that includes all of the bytes for its type -(what the `-Raw` parameter was formally doing prior to this change). - -### PowerShell as a default shell doesn't work with script command [#3319](https://github.com/PowerShell/PowerShell/issues/3319) - -On Unix, it is a convention for shells to accept `-i` for an interactive shell and many tools expect this behavior -(`script` for example, and when setting PowerShell as the default shell) -and calls the shell with the `-i` switch. -This change is breaking in that `-i` previously could be used as short hand to match `-inputformat`, -which now needs to be `-in`. - -### Typo fix in Get-ComputerInfo property name [#3167](https://github.com/PowerShell/PowerShell/issues/3167) - -`BiosSerialNumber` was misspelled as `BiosSeralNumber` and has been changed to the correct spelling. - -### Add `Get-StringHash` and `Get-FileHash` cmdlets [#3024](https://github.com/PowerShell/PowerShell/issues/3024) - -This change is that some hash algorithms are not supported by CoreFX, therefore they are no longer available: - -* `MACTripleDES` -* `RIPEMD160` - -### Add validation on `Get-*` cmdlets where passing $null returns all objects instead of error [#2672](https://github.com/PowerShell/PowerShell/issues/2672) - -Passing `$null` to any of the following now throws an error: - -* `Get-Credential -UserName` -* `Get-Event -SourceIdentifier` -* `Get-EventSubscriber -SourceIdentifier` -* `Get-Help -Name` -* `Get-PSBreakpoint -Script` -* `Get-PSProvider -PSProvider` -* `Get-PSSessionConfiguration -Name` -* `Get-PSSnapin -Name` -* `Get-Runspace -Name` -* `Get-RunspaceDebug -RunspaceName` -* `Get-Service -Name` -* `Get-TraceSource -Name` -* `Get-Variable -Name` -* `Get-WmiObject -Class` -* `Get-WmiObject -Property` - -### Add support W3C Extended Log File Format in `Import-Csv` [#2482](https://github.com/PowerShell/PowerShell/issues/2482) - -Previously, the `Import-Csv` cmdlet cannot be used to directly import the log files in W3C extended log format and additional action would be required. -With this change, W3C extended log format is supported. - -### Parameter binding problem with `ValueFromRemainingArguments` in PS functions [#2035](https://github.com/PowerShell/PowerShell/issues/2035) - -`ValueFromRemainingArguments` now returns the values as an array instead of a single value which itself is an array. - -### `BuildVersion` is removed from `$PSVersionTable` [#1415](https://github.com/PowerShell/PowerShell/issues/1415) - -Remove the `BuildVersion` property from `$PSVersionTable`. This property was tied to the Windows build version. -Instead, we recommend that you use `GitCommitId` to retrieve the exact build version of PowerShell Core. - -### Changes to Web Cmdlets - -The underlying .NET API of the Web Cmdlets has been changed to `System.Net.Http.HttpClient`. -This change provides many benefits. -However, this change along with a lack of interoperability with Internet Explorer have resulted in several breaking changes within `Invoke-WebRequest` and `Invoke-RestMethod`. - -* `Invoke-WebRequest` now supports basic HTML Parsing only. `Invoke-WebRequest` always returns a `BasicHtmlWebResponseObject` object. - The `ParsedHtml` and `Forms` properties have been removed. -* `BasicHtmlWebResponseObject.Headers` values are now `String[]` instead of `String`. -* `BasicHtmlWebResponseObject.BaseResponse` is now a `System.Net.Http.HttpResponseMessage` object. -* The `Response` property on Web Cmdlet exceptions is now a `System.Net.Http.HttpResponseMessage` object. -* Strict RFC header parsing is now default for the `-Headers` and `-UserAgent` parameter. This can be bypassed with `-SkipHeaderValidation`. -* `file://` and `ftp://` URI schemes are no longer supported. -* `System.Net.ServicePointManager` settings are no longer honored. -* There is currently no certificate based authentication available on macOS. -* Use of `-Credential` over an `http://` URI will result in an error. Use an `https://` URI or supply the `-AllowUnencryptedAuthentication` parameter to suppress the error. diff --git a/docs/DOCSMIGRATION.md b/docs/DOCSMIGRATION.md new file mode 100644 index 00000000000..8fd642b0101 --- /dev/null +++ b/docs/DOCSMIGRATION.md @@ -0,0 +1,20 @@ +# Documentation Migration + +The docs folder in this repo contains a lot of documentation about the PowerShell source code and build environment. +It also has contained documentation about about installing and using Powershell. +That documentation really belongs in the [PowerShell/PowerShell-Docs](https://github.com/PowerShell/PowerShell-Docs) repo. + +We are in the process of migrating the user-focused article to the docs repo. +This file records which files have been migrated. + +## 2018-05-18 + +The folloing files have been moved to the PowerShell/PowerShell-Docs repo. + +| Original file location | New location in PowerShell/PowerShell-Docs | +|-----------------------------|--------------------------------------------------------------------------| +|docs/installation/linux.md | reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Linux.md | +|docs/installation/macos.md | reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS.md | +|docs/installation/windows.md | reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md | +|docs/BREAKINGCHANGES.md | reference/docs-conceptual/whats-new/breaking-changes-ps6.md | +|docs/KNOWNISSUES.md | reference/docs-conceptual/whats-new/known-issues-ps6.md | diff --git a/docs/KNOWNISSUES.md b/docs/KNOWNISSUES.md deleted file mode 100644 index 004756ae3ba..00000000000 --- a/docs/KNOWNISSUES.md +++ /dev/null @@ -1,166 +0,0 @@ -# Known Issues - -## Known Issues for PowerShell on Non-Windows Platforms - -Alpha releases of PowerShell on Linux and macOS are mostly functional but do have some significant limitations and usability issues. -Beta releases of PowerShell on Linux and macOS are more functional and stable than alpha releases, but still may be lacking some set of features, and can contain bugs. -In some cases, these issues are simply bugs that haven't been fixed yet. -In other cases (as with the default aliases for ls, cp, etc.), we are looking for feedback from the community regarding the choices we make. - -Note: Due to the similarities of many underlying subsystems, PowerShell on Linux and macOS tend to share the same level of maturity in both features and bugs. -Except as noted below, the issues in this section will apply to both operating systems. - -### Case-sensitivity in PowerShell - -Historically, PowerShell has been uniformly case-insensitive, with few exceptions. -On UNIX-like operating systems, the file system is predominantly case-sensitive and PowerShell adheres to the standard of the file system; this is exposed through a number of ways, obvious and non-obvious. - -#### Directly - -- When specifying a file in PowerShell, the correct case must be used. - -#### Indirectly - -- If a script tries to load a module and the module name is not cased correctly, then the module load will fail. - This may cause a problem with existing scripts if the name by which the module is referenced doesn't match the actual file name. -- Tab-completion will not auto-complete if the file name case is wrong. - The fragment to complete must be cased properly. - (Completion is case-insensitive for type name and type member completions.) - -### .PS1 File Extensions - -PowerShell scripts must end in `.ps1` for the interpreter to understand how to load and run them in the current process. -Running scripts in the current process is the expected usual behavior for PowerShell. -The `#!` magic number may be added to a script that doesn't have a `.ps1` extension, but this will cause the script to be run in a new PowerShell instance preventing the script from working properly when interchanging objects. -(Note: this may be the desirable behavior when executing a PowerShell script from `bash` or another shell.) - -### Missing command aliases - -On Linux/macOS, the "convenience aliases" for the basic commands `ls`, `cp`, `mv`, `rm`, `cat`, `man`, `mount`, `ps` have been removed. -On Windows, PowerShell provides a set of aliases that map to Linux command names for user convenience. -These aliases have been removed from the default PowerShell on Linux/macOS distributions, allowing the native executable to be run without specifying a path. - -There are pros and cons to doing this. -Removing the aliases exposes the native command experience to the PowerShell user, but reduces functionality in the shell because the native commands return strings instead of objects. - -> NOTE: This is an area where the PowerShell team is looking for feedback. -> What is the preferred solution? Should we leave it as is or add the convenience aliases back? See -> [Issue #929](https://github.com/PowerShell/PowerShell/issues/929). - -### Missing Wildcard (globbing) Support - -Currently, PowerShell only does wildcard expansion (globbing) for built-in cmdlets on Windows, and for external commands or binaries as well as cmdlets on Linux. -This means that a command like `ls *.txt` will fail because the asterisk will not be expanded to match file names. -You can work around this by doing `ls (gci *.txt | % name)` or, more simply, `gci *.txt` using the PowerShell built-in equivalent to `ls`. - -See [#954](https://github.com/PowerShell/PowerShell/issues/954) to give us feedback on how to improve the globbing experience on Linux/macOS. - -### .NET Framework vs .NET Core Framework - -PowerShell on Linux/macOS uses .NET Core which is a subset of the full .NET Framework on Microsoft Windows. -This is significant because PowerShell provides direct access to the underlying framework types, methods, etc. -As a result, scripts that run on Windows may not run on non-Windows platforms because of the differences in the frameworks. -For more information about .NET Core Framework, see - -With the advent of [.NET Standard 2.0](https://blogs.msdn.microsoft.com/dotnet/2016/09/26/introducing-net-standard/), .NET Core 2.0 will bring back many of the traditional types and methods present in the full .NET Framework. -This means that PowerShell Core will be able to load many traditional Windows PowerShell modules without modification. -You can follow our .NET Standard 2.0 related work [here](https://github.com/PowerShell/PowerShell/projects/4). - -### Redirection Issues - -Input redirection is not supported in PowerShell on any platform. -[Issue #1629](https://github.com/PowerShell/PowerShell/issues/1629) - -Use `Get-Content` to write the contents of a file into the pipeline. - -Redirected output will contain the Unicode byte order mark (BOM) when the default UTF-8 encoding is used. -The BOM will cause problems when working with utilities that do not expect it or when appending to a file. -Use `-Encoding Ascii` to write ASCII text (which, not being Unicode, will not have a BOM). -(Note: see [RFC0020](https://github.com/PowerShell/PowerShell-RFC/issues/71) to give us feedback on improving the encoding experience for PowerShell Core across all platforms. -We are working to support UTF-8 without a BOM and potentially changing the encoding defaults for various cmdlets across platforms.) - -### Job Control - -There is no job-control support in PowerShell on Linux/macOS. -The `fg` and `bg` commands are not available. - -For the time being, you can use [PowerShell jobs](https://msdn.microsoft.com/powershell/reference/5.1/microsoft.powershell.core/about/about_jobs) which do work across all platforms. - -### Remoting Support - -Currently, PowerShell Core supports PowerShell Remoting (PSRP) over WSMan with Basic authentication on macOS and Linux, and with NTLM-based authentication on Linux. -(Kerberos-based authentication is not supported.) - -The work for WSMan-based remoting is being done in the [psl-omi-provider](https://github.com/PowerShell/psl-omi-provider) repo. - -PowerShell Core also supports PowerShell Remoting (PSRP) over SSH on all platforms (Windows, macOS, and Linux). -While this is not currently supported in production, you can learn more about setting this up [here](https://docs.microsoft.com/powershell/scripting/core-powershell/ssh-remoting-in-powershell-core). - -### Just-Enough-Administration (JEA) Support - -The ability to create constrained administration (JEA) remoting endpoints is not currently available in PowerShell on Linux/macOS. -This feature is currently not in scope for 6.0 and something we will consider post 6.0 as it requires significant design work. - -### `sudo`, `exec`, and PowerShell - -Because PowerShell runs most commands in memory (like Python or Ruby), you can't use sudo directly with PowerShell built-ins. -(You can, of course, run `powershell` from sudo.) -If it is necessary to run a PowerShell cmdlet from within PowerShell with sudo, for example, `sudo Set-Date 8/18/2016`, then you would do `sudo powershell Set-Date 8/18/2016`. -Likewise, you can't exec a PowerShell built-in directly. -Instead you would have to do `exec powershell item_to_exec`. - -This issue is currently being tracked as part of #3232. - -### Missing Cmdlets - -A large number of the commands (cmdlets) normally available in PowerShell are not available on Linux/macOS. -In many cases, these commands make no sense on these platforms (e.g. Windows-specific features like the registry). -Other commands like the service control commands (Get/Start/Stop-Service) are present, but not functional. -Future releases will correct these problems, fixing the broken cmdlets and adding new ones over time. - -### Command Availability - -The following table lists commands that are known not to work in PowerShell on Linux/macOS. - - - - - - - - - - - - - - - - - - - -
CommandsOperational StateNotes
Get-Service, New-Service, Restart-Service, Resume-Service, Set-Service, Start-Service, Stop-Service, Suspend-Service -Not available. -These commands will not be recognized. This should be fixed in a future release. -
Get-Acl, Set-Acl -Not available. -These commands will not be recognized. This should be fixed in a future release. -
Get-AuthenticodeSignature, Set-AuthenticodeSignature -Not available. -These commands will not be recognized. This should be fixed in a future release. -
Wait-Process -Available, doesn't work properly. For example `Start-Process gvim -PassThru | Wait-Process` doesn't work; it fails to wait for the process. -
Register-PSSessionConfiguration, Unregister-PSSessionConfiguration, Get-PSSessionConfiguration -Available but doesn't work. -Writes an error message indicating that the commands are not working. These should be fixed in a future release. -
Get-Event, New-Event, Register-EngineEvent, Register-WmiEvent, Remove-Event, Unregister-Event -Available but no event sources are available. -The PowerShell eventing commands are present but most of the event sources used with the commands (such as System.Timers.Timer) are not available on Linux making the commands useless in the Alpha release. -
Set-ExecutionPolicy -Available but doesn't work. -Returns a message saying not supported on this platform. Execution policy is a user-focused "safety belt" that helps prevent the user from making expensive mistakes. It is not a security boundary. -
New-PSSessionOption, New-PSTransportOption -Available but New-PSSession doesn't work. -New-PSSessionOption and New-PSTransportOption are not currently verified to work now that New-PSSession works. -
diff --git a/docs/installation/linux.md b/docs/installation/linux.md deleted file mode 100644 index 9d5832a2459..00000000000 --- a/docs/installation/linux.md +++ /dev/null @@ -1,731 +0,0 @@ -# Package Installation Instructions - -Supports [Ubuntu 14.04][u14], [Ubuntu 16.04][u16], [Ubuntu 17.04][u17], [Debian 8][deb8], [Debian 9][deb9], -[CentOS 7][cos], [Red Hat Enterprise Linux (RHEL) 7][rhel7], [OpenSUSE 42.2][opensuse], [Fedora 25][fed25], -[Fedora 26][fed26], [Arch Linux][arch], [Kali Linux][kali] and [Raspbian][rasp]. - -For Linux distributions that are not officially supported, -you can try using the [PowerShell AppImage][lai]. -You can also try deploying PowerShell binaries directly using the Linux [`tar.gz` archive][tar], -but you would need to set up the necessary dependencies based on the OS in separate steps. - -All packages are available on our GitHub [releases][] page. -Once the package is installed, run `pwsh` from a terminal. - -[u14]: #ubuntu-1404 -[u16]: #ubuntu-1604 -[u17]: #ubuntu-1704 -[deb8]: #debian-8 -[deb9]: #debian-9 -[cos]: #centos-7 -[rhel7]: #red-hat-enterprise-linux-rhel-7 -[opensuse]: #opensuse-422 -[fed25]: #fedora-25 -[fed26]: #fedora-26 -[arch]: #arch-linux -[kali]: #kali -[rasp]: #raspbian -[lai]: #linux-appimage -[mac]: #macos-1012 -[tar]: #binary-archives - -## Ubuntu 14.04 - -### Installation via Package Repository - Ubuntu 14.04 - -PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). -This is the preferred method. - -```sh -# Import the public repository GPG keys -curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - - -# Register the Microsoft Ubuntu repository -sudo curl -o /etc/apt/sources.list.d/microsoft.list https://packages.microsoft.com/config/ubuntu/14.04/prod.list - -# Update the list of products -sudo apt-get update - -# Install PowerShell -sudo apt-get install -y powershell - -# Start PowerShell -pwsh -``` - -After registering the Microsoft repository once as superuser, -from then on, you just need to use `sudo apt-get upgrade powershell` to update it. - -### Installation via Direct Download - Ubuntu 14.04 - -Download the Debian package -`powershell_6.0.2-1.ubuntu.14.04_amd64.deb` -from the [releases][] page onto the Ubuntu machine. - -Then execute the following in the terminal: - -```sh -sudo dpkg -i powershell_6.0.2-1.ubuntu.14.04_amd64.deb -sudo apt-get install -f -``` - -> Please note that `dpkg -i` will fail with unmet dependencies; -> the next command, `apt-get install -f` resolves these -> and then finishes configuring the PowerShell package. - -### Uninstallation - Ubuntu 14.04 - -```sh -sudo apt-get remove powershell -``` - -## Ubuntu 16.04 - -### Installation via Package Repository - Ubuntu 16.04 - -PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). -This is the preferred method. - -```sh -# Import the public repository GPG keys -curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - - -# Register the Microsoft Ubuntu repository -sudo curl -o /etc/apt/sources.list.d/microsoft.list https://packages.microsoft.com/config/ubuntu/16.04/prod.list - -# Update the list of products -sudo apt-get update - -# Install PowerShell -sudo apt-get install -y powershell - -# Start PowerShell -pwsh -``` - -After registering the Microsoft repository once as superuser, -from then on, you just need to use `sudo apt-get upgrade powershell` to update it. - -### Installation via Direct Download - Ubuntu 16.04 - -Download the Debian package -`powershell_6.0.2-1.ubuntu.16.04_amd64.deb` -from the [releases][] page onto the Ubuntu machine. - -Then execute the following in the terminal: - -```sh -sudo dpkg -i powershell_6.0.2-1.ubuntu.16.04_amd64.deb -sudo apt-get install -f -``` - -> Please note that `dpkg -i` will fail with unmet dependencies; -> the next command, `apt-get install -f` resolves these -> and then finishes configuring the PowerShell package. - -### Uninstallation - Ubuntu 16.04 - -```sh -sudo apt-get remove powershell -``` - -## Ubuntu 17.04 - -### Installation via Package Repository - Ubuntu 17.04 - -PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). -This is the preferred method. - -```sh -# Import the public repository GPG keys -curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - - -# Register the Microsoft Ubuntu repository -sudo curl -o /etc/apt/sources.list.d/microsoft.list https://packages.microsoft.com/config/ubuntu/17.04/prod.list - -# Update the list of products -sudo apt-get update - -# Install PowerShell -sudo apt-get install -y powershell - -# Start PowerShell -pwsh -``` - -After registering the Microsoft repository once as superuser, -from then on, you just need to use `sudo apt-get upgrade powershell` to update it. - -### Installation via Direct Download - Ubuntu 17.04 - -Download the Debian package -`powershell_6.0.2-1.ubuntu.17.04_amd64.deb` -from the [releases][] page onto the Ubuntu machine. - -Then execute the following in the terminal: - -```sh -sudo dpkg -i powershell_6.0.2-1.ubuntu.17.04_amd64.deb -sudo apt-get install -f -``` - -> Please note that `dpkg -i` will fail with unmet dependencies; -> the next command, `apt-get install -f` resolves these -> and then finishes configuring the PowerShell package. - -### Uninstallation - Ubuntu 17.04 - -```sh -sudo apt-get remove powershell -``` - -## Debian 8 - -### Installation via Package Repository - Debian 8 - -PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). -This is the preferred method. - -```sh -# Install system components -sudo apt-get update -sudo apt-get install curl apt-transport-https - -# Import the public repository GPG keys -curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - - -# Register the Microsoft Product feed -sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-debian-jessie-prod jessie main" > /etc/apt/sources.list.d/microsoft.list' - -# Update the list of products -sudo apt-get update - -# Install PowerShell -sudo apt-get install -y powershell - -# Start PowerShell -pwsh -``` - -After registering the Microsoft repository once as superuser, -from then on, you just need to use `sudo apt-get upgrade powershell` to update it. - -### Installation via Direct Download - Debian 8 - -Download the Debian package -`powershell_6.0.2-1.debian.8_amd64.deb` -from the [releases][] page onto the Debian machine. - -Then execute the following in the terminal: - -```sh -sudo dpkg -i powershell_6.0.2-1.debian.8_amd64.deb -sudo apt-get install -f -``` - -> Please note that `dpkg -i` will fail with unmet dependencies; -> the next command, `apt-get install -f` resolves these -> and then finishes configuring the PowerShell package. - -### Uninstallation - Debian 8 - -```sh -sudo apt-get remove powershell -``` - -## Debian 9 - -### Installation via Package Repository - Debian 9 - -PowerShell Core, for Linux, is published to package repositories for easy installation (and updates). -This is the preferred method. - -```sh -# Install system components -sudo apt-get update -sudo apt-get install curl gnupg apt-transport-https - -# Import the public repository GPG keys -curl https://packages.microsoft.com/keys/microsoft.asc | sudo apt-key add - - -# Register the Microsoft Product feed -sudo sh -c 'echo "deb [arch=amd64] https://packages.microsoft.com/repos/microsoft-debian-stretch-prod stretch main" > /etc/apt/sources.list.d/microsoft.list' - -# Update the list of products -sudo apt-get update - -# Install PowerShell -sudo apt-get install -y powershell - -# Start PowerShell -pwsh -``` - -After registering the Microsoft repository once as superuser, -from then on, you just need to use `sudo apt-get upgrade powershell` to update it. - -### Installation via Direct Download - Debian 9 - -Download the Debian package -`powershell_6.0.2-1.debian.9_amd64.deb` -from the [releases][] page onto the Debian machine. - -Then execute the following in the terminal: - -```sh -sudo dpkg -i powershell_6.0.2-1.debian.9_amd64.deb -sudo apt-get install -f -``` - -> Please note that `dpkg -i` will fail with unmet dependencies; -> the next command, `apt-get install -f` resolves these -> and then finishes configuring the PowerShell package. - -### Uninstallation - Debian 9 - -```sh -sudo apt-get remove powershell -``` - -## CentOS 7 - -> This package also works on Oracle Linux 7. - -### Installation via Package Repository (preferred) - CentOS 7 - -PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). - -```sh -# Register the Microsoft RedHat repository -curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo - -# Install PowerShell -sudo yum install -y powershell - -# Start PowerShell -pwsh -``` - -After registering the Microsoft repository once as superuser, -you just need to use `sudo yum update powershell` to update PowerShell. - -### Installation via Direct Download - CentOS 7 - -Using [CentOS 7][], download the RPM package -`powershell-6.0.2-1.rhel.7.x86_64.rpm` -from the [releases][] page onto the CentOS machine. - -Then execute the following in the terminal: - -```sh -sudo yum install powershell-6.0.2-1.rhel.7.x86_64.rpm -``` - -You can also install the RPM without the intermediate step of downloading it: - -```sh -sudo yum install https://github.com/PowerShell/PowerShell/releases/download/v6.0.2/powershell-6.0.2-1.rhel.7.x86_64.rpm -``` - -### Uninstallation - CentOS 7 - -```sh -sudo yum remove powershell -``` - -[CentOS 7]: https://www.centos.org/download/ - -## Red Hat Enterprise Linux (RHEL) 7 - -### Installation via Package Repository (preferred) - Red Hat Enterprise Linux (RHEL) 7 - -PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). - -```sh -# Register the Microsoft RedHat repository -curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo - -# Install PowerShell -sudo yum install -y powershell - -# Start PowerShell -pwsh -``` - -After registering the Microsoft repository once as superuser, -you just need to use `sudo yum update powershell` to update PowerShell. - -### Installation via Direct Download - Red Hat Enterprise Linux (RHEL) 7 - -Download the RPM package -`powershell-6.0.2-1.rhel.7.x86_64.rpm` -from the [releases][] page onto the Red Hat Enterprise Linux machine. - -Then execute the following in the terminal: - -```sh -sudo yum install powershell-6.0.2-1.rhel.7.x86_64.rpm -``` - -You can also install the RPM without the intermediate step of downloading it: - -```sh -sudo yum install https://github.com/PowerShell/PowerShell/releases/download/v6.0.2/powershell-6.0.2-1.rhel.7.x86_64.rpm -``` - -### Uninstallation - Red Hat Enterprise Linux (RHEL) 7 - -```sh -sudo yum remove powershell -``` - -## OpenSUSE 42.2 - -> **Note:** When installing PowerShell Core, OpenSUSE may report that nothing provides `libcurl`. -`libcurl` should already be installed on supported versions of OpenSUSE. -Run `zypper search libcurl` to confirm. -The error will present 2 'solutions'. Choose 'Solution 2' to continue installing PowerShell Core. - -### Installation via Package Repository (preferred) - OpenSUSE 42.2 - -PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). - -```sh -# Register the Microsoft signature key -sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc - -# Add the Microsoft Product feed -curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/zypp/repos.d/microsoft.repo - -# Update the list of products -sudo zypper update - -# Install PowerShell -sudo zypper install powershell - -# Start PowerShell -pwsh -``` - -### Installation via Direct Download - OpenSUSE 42.2 - -Download the RPM package `powershell-6.0.2-1.rhel.7.x86_64.rpm` -from the [releases][] page onto the OpenSUSE machine. - -```sh -sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc -sudo zypper install powershell-6.0.2-1.rhel.7.x86_64.rpm -``` - -You can also install the RPM without the intermediate step of downloading it: - -```sh -sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc -sudo zypper install https://github.com/PowerShell/PowerShell/releases/download/v6.0.2/powershell-6.0.2-1.rhel.7.x86_64.rpm -``` - -### Uninstallation - OpenSUSE 42.2 - -```sh -sudo zypper remove powershell -``` - -## Fedora 25 - -### Installation via Package Repository (preferred) - Fedora 25 - -PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). - -```sh -# Register the Microsoft signature key -sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc - -# Register the Microsoft RedHat repository -curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo - -# Update the list of products -sudo dnf update - -# Install PowerShell -sudo dnf install -y powershell - -# Start PowerShell -pwsh -``` - -### Installation via Direct Download - Fedora 25 - -Download the RPM package -`powershell-6.0.2-1.rhel.7.x86_64.rpm` -from the [releases][] page onto the Fedora machine. - -Then execute the following in the terminal: - -```sh -sudo dnf install powershell-6.0.2-1.rhel.7.x86_64.rpm -``` - -You can also install the RPM without the intermediate step of downloading it: - -```sh -sudo dnf install https://github.com/PowerShell/PowerShell/releases/download/v6.0.2/powershell-6.0.2-1.rhel.7.x86_64.rpm -``` - -### Uninstallation - Fedora 25 - -```sh -sudo dnf remove powershell -``` - -## Fedora 26 - -### Installation via Package Repository (preferred) - Fedora 26 - -PowerShell Core for Linux is published to official Microsoft repositories for easy installation (and updates). - -```sh -# Register the Microsoft signature key -sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc - -# Register the Microsoft RedHat repository -curl https://packages.microsoft.com/config/rhel/7/prod.repo | sudo tee /etc/yum.repos.d/microsoft.repo - -# Update the list of products -sudo dnf update - -# Install a system component -sudo dnf install compat-openssl10 - -# Install PowerShell -sudo dnf install -y powershell - -# Start PowerShell -pwsh -``` - -### Installation via Direct Download - Fedora 26 - -Download the RPM package -`powershell-6.0.2-1.rhel.7.x86_64.rpm` -from the [releases][] page onto the Fedora machine. - -Then execute the following in the terminal: - -```sh -sudo dnf update -sudo dnf install compat-openssl10 -sudo dnf install powershell-6.0.2-1.rhel.7.x86_64.rpm -``` - -You can also install the RPM without the intermediate step of downloading it: - -```sh -sudo dnf update -sudo dnf install compat-openssl10 -sudo dnf install https://github.com/PowerShell/PowerShell/releases/download/v6.0.2/powershell-6.0.2-1.rhel.7.x86_64.rpm -``` - -### Uninstallation - Fedora 26 - -```sh -sudo dnf remove powershell -``` - -## Arch Linux - -PowerShell is available from the [Arch Linux][] User Repository (AUR). - -* It can be compiled with the [latest tagged release][arch-release] -* It can be compiled from the [latest commit to master][arch-git] -* It can be installed using the [latest release binary][arch-bin] - -Packages in the AUR are community maintained - there is no official support. - -For more information on installing packages from the AUR, see the [Arch Linux wiki](https://wiki.archlinux.org/index.php/Arch_User_Repository#Installing_packages) or the community [DockerFile](https://github.com/PowerShell/PowerShell/blob/master/docker/community/archlinux/Dockerfile). - -[Arch Linux]: https://www.archlinux.org/download/ -[arch-release]: https://aur.archlinux.org/packages/powershell/ -[arch-git]: https://aur.archlinux.org/packages/powershell-git/ -[arch-bin]: https://aur.archlinux.org/packages/powershell-bin/ - -## Linux AppImage - -Using a recent Linux distribution, -download the AppImage `powershell-6.0.1-x86_64.AppImage` -from the [releases][] page onto the Linux machine. - -Then execute the following in the terminal: - -```bash -chmod a+x powershell-6.0.1-x86_64.AppImage -./powershell-6.0.1-x86_64.AppImage -``` - -The [AppImage][] lets you run PowerShell without installing it. -It is a portable application that bundles PowerShell and its dependencies -(including .NET Core's system dependencies) into one cohesive package. -This package works independently of the user's Linux distribution, -and is a single binary. - -[appimage]: http://appimage.org/ - -## Kali - -### Installation - -```sh -# Install prerequisites -apt-get install libunwind8 libicu55 -wget http://security.debian.org/debian-security/pool/updates/main/o/openssl/libssl1.0.0_1.0.1t-1+deb8u6_amd64.deb -dpkg -i libssl1.0.0_1.0.1t-1+deb8u6_amd64.deb - -# Install PowerShell -dpkg -i powershell_6.0.2-1.ubuntu.16.04_amd64.deb - -# Start PowerShell -pwsh -``` - -### Run PowerShell in latest Kali (Kali GNU/Linux Rolling) without installing it - -```sh -# Grab the latest App Image -wget https://github.com/PowerShell/PowerShell/releases/download/v6.0.2/powershell-6.0.2-x86_64.AppImage - -# Make executable -chmod a+x powershell-6.0.2-x86_64.AppImage - -# Start PowerShell -./powershell-6.0.2-x86_64.AppImage -``` - -### Uninstallation - Kali - -```sh -dpkg -r powershell_6.0.2-1.ubuntu.16.04_amd64.deb -``` - -## Raspbian - -Currently, PowerShell is only supported on Raspbian Stretch. - -Also CoreCLR (and thus PowerShell Core) will only work on Pi 2 and Pi 3 devices as other devices like [Pi Zero](https://github.com/dotnet/coreclr/issues/10605) have an unsupported processor. - -Download [Raspbian Stretch](https://www.raspberrypi.org/downloads/raspbian/) and follow the [installation instructions](https://www.raspberrypi.org/documentation/installation/installing-images/README.md) to get it onto your Pi. - -### Installation - -```sh -# Install prerequisites -sudo apt-get install libunwind8 - -# Grab the latest tar.gz -wget https://github.com/PowerShell/PowerShell/releases/download/v6.0.2/powershell-6.0.2-linux-arm32.tar.gz - -# Make folder to put powershell -mkdir ~/powershell - -# Unpack the tar.gz file -tar -xvf ./powershell-6.0.2-linux-arm32.tar.gz -C ~/powershell - -# Start PowerShell -~/powershell/pwsh -``` - -Optionally you can create a symbolic link to be able to start PowerShell without specifying path to the "pwsh" binary - -```sh -# Start PowerShell from bash with sudo to create a symbolic link -sudo ~/powershell/pwsh -c New-Item -ItemType SymbolicLink -Path "/usr/bin/pwsh" -Target "$PSHOME/pwsh" -Force - -# alternatively you can run following to create a symbolic link -sudo ln -s ~/powershell/pwsh /usr/bin/pwsh - -# Now to start PowerShell you can just run "pwsh" -pwsh -``` - -### Uninstallation - Raspbian - -```sh -rm -rf ~/powershell -``` - -## Binary Archives - -PowerShell binary `tar.gz` archives are provided for macOS and Linux platforms to enable advanced deployment scenarios. - -### Dependencies - -For Linux, PowerShell builds portable binaries for all Linux distributions. -But .NET Core runtime requires different dependencies on different distributions, -and hence PowerShell does the same. - -The following chart shows the .NET Core 2.0 dependencies on different Linux distributions that are officially supported. - -| OS | Dependencies | -| ------------------ | ------------ | -| Ubuntu 14.04 | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu52 | -| Ubuntu 16.04 | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu55 | -| Ubuntu 17.04 | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu57 | -| Debian 8 (Jessie) | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.0, libicu52 | -| Debian 9 (Stretch) | libc6, libgcc1, libgssapi-krb5-2, liblttng-ust0, libstdc++6,
libcurl3, libunwind8, libuuid1, zlib1g, libssl1.0.2, libicu57 | -| CentOS 7
Oracle Linux 7
RHEL 7
OpenSUSE 42.2
Fedora 25 | libunwind, libcurl, openssl-libs, libicu | -| Fedora 26 | libunwind, libcurl, openssl-libs, libicu, compat-openssl10 | - -In order to deploy PowerShell binaries on Linux distributions that are not officially supported, -you would need to install the necessary dependencies for the target OS in separate steps. -For example, our [Amazon Linux dockerfile][amazon-dockerfile] installs dependencies first, -and then extracts the Linux `tar.gz` archive. - -[amazon-dockerfile]: https://github.com/PowerShell/PowerShell/blob/master/docker/community/amazonlinux/Dockerfile - -### Installation - Binary Archives - -#### Linux - -```sh -# Download the powershell '.tar.gz' archive -curl -L -o /tmp/powershell.tar.gz https://github.com/PowerShell/PowerShell/releases/download/v6.0.2/powershell-6.0.2-linux-x64.tar.gz - -# Create the target folder where powershell will be placed -sudo mkdir -p /opt/microsoft/powershell/6.0.2 - -# Expand powershell to the target folder -sudo tar zxf /tmp/powershell.tar.gz -C /opt/microsoft/powershell/6.0.2 - -# Set execute permissions -sudo chmod +x /opt/microsoft/powershell/6.0.2/pwsh - -# Create the symbolic link that points to pwsh -sudo ln -s /opt/microsoft/powershell/6.0.2/pwsh /usr/bin/pwsh -``` - -### Uninstallation - Binary Archives - -```sh -sudo rm -rf /usr/bin/pwsh /opt/microsoft/powershell -``` - -## Paths - -* `$PSHOME` is `/opt/microsoft/powershell/6.0.2/` -* User profiles will be read from `~/.config/powershell/profile.ps1` -* Default profiles will be read from `$PSHOME/profile.ps1` -* User modules will be read from `~/.local/share/powershell/Modules` -* Shared modules will be read from `/usr/local/share/powershell/Modules` -* Default modules will be read from `$PSHOME/Modules` -* PSReadline history will be recorded to `~/.local/share/powershell/PSReadLine/ConsoleHost_history.txt` - -The profiles respect PowerShell's per-host configuration, -so the default host-specific profiles exists at `Microsoft.PowerShell_profile.ps1` in the same locations. - -On Linux and macOS, the [XDG Base Directory Specification][xdg-bds] is respected. - -Note that because macOS is a derivation of BSD, -instead of `/opt`, the prefix used is `/usr/local`. -Thus, `$PSHOME` is `/usr/local/microsoft/powershell/6.0.2/`, -and the symlink is placed at `/usr/local/bin/pwsh`. - -[releases]: https://github.com/PowerShell/PowerShell/releases/latest -[xdg-bds]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html diff --git a/docs/installation/macos.md b/docs/installation/macos.md deleted file mode 100644 index 4163699b46e..00000000000 --- a/docs/installation/macos.md +++ /dev/null @@ -1,102 +0,0 @@ -# Package Installation Instructions - -## macOS 10.12+ - -### Installation via Homebrew (preferred) - -[Homebrew][brew] is the missing package manager for macOS. -If the `brew` command is not found, -you need to install Homebrew following [their instructions][brew]. - -Once you've installed Homebrew, installing PowerShell is easy. -First, install [Homebrew-Cask][cask], so you can install more packages: - -```sh -brew tap caskroom/cask -``` - -Now, you can install PowerShell: - -```sh -brew cask install powershell -``` - -Finally, verify that your install is working properly: - -```sh -pwsh -``` - -When new versions of PowerShell are released, -simply update Homebrew's formulae and upgrade PowerShell: - -```sh -brew update -brew cask upgrade powershell -``` - -[brew]: http://brew.sh/ -[cask]: https://caskroom.github.io/ - -### Installation via Direct Download - -Using macOS 10.12+, download the PKG package -`powershell-6.0.2-osx.10.12-x64.pkg` -from the [releases][] page onto the macOS machine. - -Either double-click the file and follow the prompts, -or install it from the terminal: - -```sh -sudo installer -pkg powershell-6.0.2-osx.10.12-x64.pkg -target / -``` - -[releases]: https://github.com/PowerShell/PowerShell/releases - -### Installation via Binary Archive - -```sh -# Download the powershell '.tar.gz' archive -curl -L -o /tmp/powershell.tar.gz https://github.com/PowerShell/PowerShell/releases/download/v6.0.2/powershell-6.0.2-osx-x64.tar.gz - -# Create the target folder where powershell will be placed -sudo mkdir -p /usr/local/microsoft/powershell/6.0.2 - -# Expand powershell to the target folder -sudo tar zxf /tmp/powershell.tar.gz -C /usr/local/microsoft/powershell/6.0.2 - -# Set execute permissions -sudo chmod +x /usr/local/microsoft/powershell/6.0.2/pwsh - -# Create the symbolic link that points to pwsh -sudo ln -s /usr/local/microsoft/powershell/6.0.2/pwsh /usr/local/bin/pwsh -``` - -### Uninstallation - -If you installed PowerShell with Homebrew, uninstallation is easy: - -```sh -brew cask uninstall powershell -``` - -If you installed PowerShell via direct download, -PowerShell must be removed manually: - -```sh -sudo rm -rf /usr/local/microsoft /Applications/PowerShell.app -sudo rm -f /usr/local/bin/pwsh /usr/local/share/man/man1/pwsh.1.gz -sudo pkgutil --forget com.microsoft.powershell -``` - -If you installed PowerShell via binary archive, PowerShell must be removed manually. - -```sh -sudo rm -rf /usr/local/microsoft -sudo rm -f /usr/local/bin/pwsh -``` - -To uninstall the additional PowerShell paths (such as the user profile path) -please see the [paths](linux.md#path) section below in this document -and remove the desired the paths with `sudo rm`. -(Note: this is not necessary if you installed with Homebrew.) diff --git a/docs/installation/windows.md b/docs/installation/windows.md deleted file mode 100644 index 660f8a1c9e1..00000000000 --- a/docs/installation/windows.md +++ /dev/null @@ -1,194 +0,0 @@ -# Package Installation Instructions - -## MSI - -To install PowerShell on Windows Full SKU (works on Windows 7 SP1 and later), download either the MSI from [AppVeyor][] for a nightly build, -or a released package from our GitHub [releases][] page. - -Once downloaded, double-click the installer and follow the prompts. - -There is a shortcut placed in the Start Menu upon installation. - -* By default the package is installed to `$env:ProgramFiles\PowerShell\` -* You can launch PowerShell via the Start Menu or `pwsh` from a new command prompt. - -### Prerequisites - -To enable PowerShell remoting over WinRM, the following prerequisites need to be met: - -* Install the [Universal C Runtime](https://www.microsoft.com/download/details.aspx?id=50410) on Windows versions prior to Windows 10. - It is available via direct download or Windows Update. - Fully patched (including optional packages), supported systems will already have this installed. -* 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. - -## 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. - -## 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 -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 -Copy-Item .\PowerShell-6.0.2-win-arm32.zip -Destination u:\users\administrator\Downloads -ToSession $s -``` - -* Connect to the device and expand the archive - -```powershell -Enter-PSSession $s -cd u:\users\administrator\downloads -Expand-Archive .\PowerShell-6.0.2-win-arm32.zip -``` - -* Setup remoting to PowerShell Core 6 - -```powershell -cd .\PowerShell-6.0.2-win-arm32 -# 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 -Enter-PSSession -ComputerName -Credential Administrator -Configuration powershell.6.0.2 -``` - -## Deploying on Nano Server - -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). -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. -1. Online - Transfer the zip file over a PowerShell Session and unzip it in your chosen location. - -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. - -### Offline Deployment of PowerShell Core - -1. Use your favorite zip utility to unzip the package to a directory within the mounted Nano Server image. -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). - -### Online Deployment of PowerShell Core - -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 - -```powershell -$session = New-PSSession -ComputerName -Credential -``` - -* Copy the file to the Nano Server instance - -```powershell -Copy-Item \powershell--win-x64.zip c:\ -ToSession $session -``` - -* Enter the session - -```powershell -Enter-PSSession $session -``` - -* Extract the Zip file - -```powershell -# Insert the appropriate version. -Expand-Archive -Path C:\powershell--win-x64.zip -DestinationPath "C:\PowerShellCore_" -``` - -* 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 - -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. - -### 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 plug-in within %windir%\System32\PowerShell -1. Copies pwrshplugin.dll to that location -1. Generates a configuration file -1. Registers that plug-in 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 "" -``` - -For Example: - -``` powershell -& 'C:\Program Files\PowerShell\6.0.2\Install-PowerShellRemoting.ps1' -PowerShellHome 'C:\Program Files\PowerShell\6.0.2\' -``` - -**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. - -## 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.2" -Enter-PSSession ... -ConfigurationName "powershell.6.0.2" -``` - -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 bits on every CI build with [AppVeyor][]. - -[releases]: https://github.com/PowerShell/PowerShell/releases -[signing]: ../../tools/Sign-Package.ps1 -[AppVeyor]: https://ci.appveyor.com/project/PowerShell/powershell - -## CoreCLR Artifacts - -* Download zip package from **artifacts** tab of the particular build. -* Unblock zip file: right-click in File Explorer -> Properties -> - check 'Unblock' box -> apply -* Extract zip file to `bin` directory -* `./bin/pwsh.exe` From 34eb21b725ddf417ca8b1af9bfafebe08c838777 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 18 May 2018 10:53:25 -0700 Subject: [PATCH 2/3] fix typo --- docs/DOCSMIGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DOCSMIGRATION.md b/docs/DOCSMIGRATION.md index 8fd642b0101..47022100b9e 100644 --- a/docs/DOCSMIGRATION.md +++ b/docs/DOCSMIGRATION.md @@ -9,7 +9,7 @@ This file records which files have been migrated. ## 2018-05-18 -The folloing files have been moved to the PowerShell/PowerShell-Docs repo. +The following files have been moved to the PowerShell/PowerShell-Docs repo. | Original file location | New location in PowerShell/PowerShell-Docs | |-----------------------------|--------------------------------------------------------------------------| From 0b9d8f91f20d0e72b6afec58ef65ba8266474c61 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Fri, 25 May 2018 09:53:09 -0700 Subject: [PATCH 3/3] fix formatting to avoid spell check --- docs/DOCSMIGRATION.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/DOCSMIGRATION.md b/docs/DOCSMIGRATION.md index 47022100b9e..ab704845d36 100644 --- a/docs/DOCSMIGRATION.md +++ b/docs/DOCSMIGRATION.md @@ -11,10 +11,10 @@ This file records which files have been migrated. The following files have been moved to the PowerShell/PowerShell-Docs repo. -| Original file location | New location in PowerShell/PowerShell-Docs | -|-----------------------------|--------------------------------------------------------------------------| -|docs/installation/linux.md | reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Linux.md | -|docs/installation/macos.md | reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS.md | -|docs/installation/windows.md | reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md | -|docs/BREAKINGCHANGES.md | reference/docs-conceptual/whats-new/breaking-changes-ps6.md | -|docs/KNOWNISSUES.md | reference/docs-conceptual/whats-new/known-issues-ps6.md | +| Original file location | New location in PowerShell/PowerShell-Docs | +|--------------------------------|----------------------------------------------------------------------------| +| `docs/installation/linux.md` | `reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Linux.md` | +| `docs/installation/macos.md` | `reference/docs-conceptual/setup/Installing-PowerShell-Core-on-macOS.md` | +| `docs/installation/windows.md` | `reference/docs-conceptual/setup/Installing-PowerShell-Core-on-Windows.md` | +| `docs/BREAKINGCHANGES.md` | `reference/docs-conceptual/whats-new/breaking-changes-ps6.md` | +| `docs/KNOWNISSUES.md` | `reference/docs-conceptual/whats-new/known-issues-ps6.md` |