diff --git a/KNOWNISSUES.md b/KNOWNISSUES.md new file mode 100644 index 000000000..ff0c264db --- /dev/null +++ b/KNOWNISSUES.md @@ -0,0 +1,34 @@ +# Known Issues + +## xUnit + +The xUnit tests cannot currently be run; we are working to integrate the +prototype .NET Core runner to re-enable them. + +## Console Output + +The console output on Windows and under certain `TERM` environments on Linux +(`xterm` is known to work fine), the console scrolls badly. We believe this is +due to incomplete System.Console APIs, which have been fixed upstream and will +be updated when new packages drop. + +Performance issues have been seen in some scenarios, such as nested SSH +sessions. We believe this is likely an issue with `Console.ReadKey()` and are +investigating. + +## Remoting + +Only basic authentication is implemented + +Multiple sessions are not yet supported + +Server shut-down is not complete (must restart `omiserver` after a session is +completed. + +## Registry Use + +`SafeHandle` objects attempt to use the registry (even on Linux) so a stub is +in place to prevent error messages. This should be fixed in .NET Core. Use of +the registry is widespread throughout the PowerShell codebase, and so innocuous +things (such as loading particular modules) can cause strange behavior when +unguarded code is executed. diff --git a/README.md b/README.md index 0be1c21e0..23f22499d 100644 --- a/README.md +++ b/README.md @@ -94,6 +94,26 @@ to obtain all the necessary .NET packages.** Build with `./build.sh` on Linux and OS X, and `./build.ps1` on Windows. +Specifically: + +### Linux + +> In Bash: +```sh +cd PowerShell-Linux +dotnet restore +./build.sh +``` + +### Windows + +> In PowerShell: +```powershell +cd PowerShell-Linux +dotnet restore +./build.ps1 +``` + ## Running ### Linux / OS X @@ -108,29 +128,87 @@ Launch `./bin/powershell.exe`. The console output isn't the prettiest, but the vast majority of Pester tests pass. Run them in the console with `Invoke-Pester test/powershell`. -## Known Issues +## PowerShell Remoting Protocol -### xUnit +PSRP communication is tunneled through OMI using the `omi-provider`. -The xUnit tests cannot currently be run; we are working to integrate the -prototype .NET Core runner to re-enable them. +**These build steps are not part of the `./build.sh` script.** -### Console Output +> PSRP has been observed working on OS X, but the changes made to OMI to +> accomplish this are not even beta-ready and need to be done correctly. They +> exist on the `andschwa-osx` branch of the OMI repository. -The console output on Windows and under certain `TERM` environments on Linux -(`xterm` is known to work fine), the console scrolls badly. We believe this is -due to incomplete System.Console APIs, which have been fixed upstream and will -be updated when new packages drop. +### Build OMI -### Registry Use +```sh +cd src/omi/Unix +./configure --dev +make -j +cd ../../.. +``` -`SafeHandle` objects attempt to use the registry (even on Linux) so a stub is -in place to prevent error messages. This should be fixed in .NET Core. Use of -the registry is widespread throughout the PowerShell codebase, and so innocuous -things (such as loading particular modules) can cause strange behavior when -unguarded code is executed. +### Build Provider -## Detailed Build Notes +The provider uses CMake to build, link, and register with OMI. + +```sh +cd src/omi-provider +cmake . +make -j +cd ../.. +``` + +The provider also maintains its own native host library to initialize the CLR, +but there are plans to refactor .NET's packaged host as a shared library. + +### Running + +Some initial setup on Windows is required. Open an administrative command +prompt and execute the following: + +```cmd +winrm set winrm/config/Client @{AllowUnencrypted="true"} +winrm set winrm/config/Client @{TrustedHosts="*"} +``` + +Then on Linux, launch `omiserver` in the debugger (after building with the +instructions above): + +```sh +./psrp.sh +run +``` + +> The `run` command is executed inside of LLDB (the debugger) to start the +`omiserver` process. + +Now in a PowerShell prompt on Windows (opened after setting the WinRM client +configurations): + +```powershell +Enter-PSSession -ComputerName -Credential $cred -Authentication basic +``` + +> The `$cred` variable can be empty; a credentials prompt will appear, enter +> any fake credentials you wish as authentication is not yet implemented. + +### Desired State Configuration + +> DSC support is in its infancy. + +DSC also uses OMI, so build it first, then build DSC against it. Unfortunately, +DSC cannot be configured to look for OMI elsewhere, so for now you need to +symlink it to the expected location. + +```sh +ln -s ../omi/Unix/ omi-1.0.8 +./configure --no-rpm --no-dpkg --local +make -j +``` + +## Detailed Build Script Notes + +> This explains `./build.sh`. The variable `$BIN` is the output directory, `bin`. @@ -175,45 +253,3 @@ cd src/registry-stub make cp api-ms-win-core-registry-l1-1-0.dll $BIN ``` - -### PowerShell Remoting Protocol - -PSRP communication is tunneled through OMI using the `omi-provider`. -These build steps are not part of the `./build.sh` script. - -> PSRP has been observed working on OS X, but the changes made to OMI to -> accomplish this are not even beta-ready and need to be done correctly. They -> exist on the `andschwa-osx` branch of the OMI repository. - -#### OMI - -```sh -cd src/omi/Unix -./configure --dev -make -j -``` - -#### Provider - -The provider uses CMake to build, link, and register with OMI. - -```sh -cd src/omi-provider -cmake . -make -j -``` - -The provider also maintains its own native host library to initialize the CLR, -but there are plans to refactor .NET's packaged host as a shared library. - -### DSC - -DSC also uses OMI, so build it first, then build DSC against it. Unfortunately, -DSC cannot be configured to look for OMI elsewhere, so for now you need to -symlink it to the expected location. - -```sh -ln -s ../omi/Unix/ omi-1.0.8 -./configure --no-rpm --no-dpkg --local -make -j -```