From f1d27d518c7fb7c7a6b471576e4be9e95bf1e5eb Mon Sep 17 00:00:00 2001 From: Andrew Schwartzmeyer Date: Wed, 30 Mar 2016 15:57:52 -0700 Subject: [PATCH] Move PSRP notes --- README.md | 100 ++------------------------------------- docs/building/psrp.md | 106 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+), 96 deletions(-) create mode 100644 docs/building/psrp.md diff --git a/README.md b/README.md index d88aa5abe..2b864a84f 100644 --- a/README.md +++ b/README.md @@ -24,10 +24,10 @@ Build Status Get PowerShell -------------- -| | Linux | Windows .NET Core | Windows .NET Full | OS X | -|-----------------------|-------|-------------------|-------------------|------| -| Build from **Source** | [Instructions](docs/building/linux.md) | [Instructions](docs/building/windows-core.md) | [Instructions](docs/building/windows-full.md) | [Instructions](docs/building/osx.md) | -| Get **Binaries** | [Releases][] | [Artifacts][] | [Artifacts][] | [Releases][] | +| | Linux | Windows .NET Core | Windows .NET Full | OS X | PSRP | +|-----------------------|-------|-------------------|-------------------|------|------| +| Build from **Source** | [Instructions](docs/building/linux.md) | [Instructions](docs/building/windows-core.md) | [Instructions](docs/building/windows-full.md) | [Instructions](docs/building/osx.md) | [Instructions](docs/building/psrp.md) | +| Get **Binaries** | [Releases][] | [Artifacts][] | [Artifacts][] | [Releases][] | TBD | Building summary: `Start-PSBuild` from the module `./PowerShellGitHubDev.psm1` (self-host on Linux / OS X) @@ -98,98 +98,6 @@ powershell, then (in VS Code) press `F5` to begin the debugger. [VS Code]: https://blogs.msdn.microsoft.com/visualstudioalm/2016/03/10/experimental-net-core-debugging-in-vs-code/ [vscclrdebugger]: http://aka.ms/vscclrdebugger -## PowerShell Remoting Protocol - -PSRP communication is tunneled through OMI using the `omi-provider`. - -> 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. - -PSRP support is *not* built automatically. See the detailed notes on -how to enable it. - -### 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="*"} -``` - -> You can also set the `TrustedHosts` to include the target's IP address. - -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. - -The IP address of the Linux machine can be obtained with: - -```sh -ip -f inet addr show dev eth0 -``` - -## Detailed Build Script Notes - -> This sections explains the build scripts. - -The variable `$BIN` is the output directory, `bin`. - -### PSRP - -#### OMI - -**PSRP support is not built by `./build.sh`** - -To develop on the PowerShell Remoting Protocol (PSRP) for Linux, you'll need to -be able to compile OMI, which additionally requires: - -```sh -sudo apt-get install libpam0g-dev libssl-dev libcurl4-openssl-dev libboost-filesystem-dev -``` - -Note that the OMI build steps can be done with `./omibuild.sh`. - -Build OMI from source in developer mode: - -```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. - ### FullCLR PowerShell ## Running from CI server diff --git a/docs/building/psrp.md b/docs/building/psrp.md new file mode 100644 index 000000000..dc7065ed2 --- /dev/null +++ b/docs/building/psrp.md @@ -0,0 +1,106 @@ +PowerShell Remoting Protocol +============================ + +This guide supplements the [Linux instructions](./linux.md), as +building PowerShell Remoting Protocol (PSRP) support first requires +PowerShell on Linux built. + +PSRP communication is tunneled through the Open Management +Infrastructure (OMI) using the [`omi-provider`][]. + +> 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-provider]: https://github.com/PowerShell/psl-omi-provider/ + +Environment +=========== + +Toolchain Setup +--------------- + +PSRP requires the following additional packages: + +```sh +sudo apt-get install libpam0g-dev libssl-dev libcurl4-openssl-dev libboost-filesystem-dev +``` + +Git Setup +--------- + +Two additional submodules need to be initialized: + +```sh +git submodule update --init -- src/omi src/omi-provider +``` + +The `src/omi` submodule requires your GitHub user to have joined the +Microsoft organization. If it fails to check out, Git will give up and +not check out further submodules either. Please follow the +instructions on the [Open Source Hub][]. + +[Open Source Hub]: https://opensourcehub.microsoft.com/articles/how-to-join-microsoft-github-org-self-service + +Building +======== + +Run `./omibuild.sh` to build OMI and the provider. + +This script first builds OMI in developer mode: + +```sh +pushd src/omi/Unix +./configure --dev +make -j +popd +``` + +Then it builds and registers the provider: + +```sh +pushd src/omi-provider +cmake -DCMAKE_BUILD_TYPE=Debug . +make -j +popd +``` + +The provider 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="*"} +``` + +> You can also set the `TrustedHosts` to include the target's IP address. + +Then on Linux, launch `omiserver` (after building with the +instructions above): + +```sh +./psrp.sh +``` + +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. + +The IP address of the Linux machine can be obtained with: + +```sh +ip -f inet addr show dev eth0 +```