Secrets of PowerShell RemotingPrinciple author: Don JonesContributing author: Dr. Tobias WeltnerWith contributions by Dave Wyatt and Aleksandar NikolikCover design by Nathan Vonnahe!ntroduced in Windo"s Po"er#hell $.%& 'eoting is one o( Po"er#hell)sost use(ul& and ost iportant& core technologies. !t enables you to run alost any coand that e*ists on a reote coputer& opening up a universe o( possibilities (or bulk and reote adinistration. 'eoting underpins other technologies& including Work+o"& Desired #tate Con,guration& certain types o( background -obs& and uch ore. This guide isn)t intended to be a coplete docuent o( "hat 'eotingis and does& although it does provide a good introduction. !nstead& this guide is designed to docuent all the little con,guration details that don)t appear to be docuented else"here.Visit www.penfip.com/powershellorg to check (or ne"er editions o( thise.book.This guide is released under the Creative Coons Attribution.NoDerivs /.% 0nported 1icense. The authors encourage you to redistribute this ,le as "idely as possible& but ask that you do not odi(y the docuent.Po"er#hell.org e2ooks are "orks.in.progress& and any are curated byebers o( the counity. We encourage you to check back (or ne" editions at least t"ice a year& by visiting www.penfip.com/powershellorg.3ou can do"nload this book in a nuber o( di4erent (orats 5including 6P02& PD7& 8icroso(t Word and Plain Te*t9 by clicking Download on the right side o( the page.PD7 0sers: Pen+ip)s PD7 e*port o(ten doesn)t include the entire ebook content. We)ve reported this proble to the: in the eantie& pleaseconsider using a di4erent (orat& such as 6P02& "hen you)re do"nloading the book.3ou ay register to ake corrections& contributions& and other changesto the te*t . "e "elcoe your contributions; uarebrackets. !( you have custoi=ed your propt& all custoi=ations "ill be lost because the propt is no" created on the reote syste and trans(erred back to you. All o( your interactive keyboard input is sent tothe reote achine& and all results are arshaled back to you. This is iportant to note because you cannot use 6nter.P##ession in a script. !( you did& the script "ould still run on your local achine since no code "as entered interactively.)"to"*an+ RemotingWith this techni>ue& you speci(y one or ore coputer naes and a coand 5or a seicolon.separated list o( coands9: Po"er#hell sends the coands& via 'eoting& to the speci,ed coputers. Those coputers e*ecute the coands& seriali=e the results into M81& and transit the results back to you. 3our coputer deseriali=es the M81 back into ob-ects& and places the in the pipeline o( your Po"er#hell session. This is accoplished via the !nvoke.Coand cdlet.!nvoke.Coand .coputernae DC%B&C1!6NTB .script2lock O Jet.#ervice P!( you have a script o( coands to run& you can have !nvoke.Coand read it& transit the contents to the reote coputers& and have the e*ecute those coands.!nvoke.Coand .coputernae DC%B&C1!6NTB .,lePath c:Q#criptsQTask.psBNote that !nvoke.Coand "ill& by de(ault& counicate "ith only /$ coputers at once. !( you speci(y ore& the e*tras "ill >ueue up& and !nvoke.Coand "ill begin processing the as it ,nishes the ,rst /$. The .Throttle1iit paraeter can raise this liit: the only cost is to your coputer& "hich ust have suEcient resources to aintain a uni>ue Po"er#hell session (or each coputer you)re contacting siultaneously. !( you e*pect to receive large aounts o( data (ro thereote coputers& available net"ork band"idth can be another liiting (actor.SessionsWhen you run 6nter.P##ession or !nvoke.Coand and use their .CoputerNae paraeter& 'eoting creates a connection 5or session9& does "hatever you)ve asked it to& and then closes the connection 5in the case o( an interactive session created "ith 6nter.P##ession& Po"er#hell kno"s you)re done "hen you run 6*it.P##ession9. There)s soe overhead involved in that set.up and tear.do"n& and so Po"er#hell also o4ers the option o( creating a persistent connection . called a P##ession. 3ou run Ne".P##ession to create a ne"& persistent session. Then& rather than using .CoputerNae "ith 6nter.P##ession or !nvoke.Coand& you use their .#ession paraeterand pass an e*isting& open P##ession ob-ect. That lets the coands re.use the persistent connection you)d previously created.When you use the .CoputerNae paraeter and "ork "ith ad.hoc sessions& each tie you send a coand to a reote achine& there is a signi,cant delay caused by the overhead it takes to create a ne" session. #ince each call to 6nter.P##ession or !nvoke.Coand sets upa ne" session& you also cannot preserve state. !n the e*aple belo"& the variable Ntest is lost in the second call:P#R !nvoke.Coand .coputernae C1!6NTB .script2lock O Ntest S B PP#R !nvoke.Coand .coputernae C1!6NTB .script2lock O Ntest PP#RWhen you use persistent sessions& on the other hand& re.connections are uch (aster& and since you are keeping and reusing sessions& they "ill preserve state. #o here& the second call to !nvoke.Coand "ill still be able to access the variable Ntest that "as set up in the ,rst callP#R N#ession S Ne".P##ession .CoputerNae C1!6NTBP#R !nvoke.Coand .#ession N#ession .script2lock O Ntest S B PP#R !nvoke.Coand .#ession N#ession .script2lock O Ntest PBP#R 'eove.P##ession .#ession N#essionVarious other coands e*ist to check the session)s status and retrieve sessions 5Jet.P##ession9& close the 5'eove.P##ession9& disconnect and reconnect the 5Disconnect.P##ession and 'econnect.P##ession& "hich are ne" in Po"er#hell v/9& and so on. !n Po"er#hell v/& you can also pass an open session to Jet.8odule and !port.8odule& enabling you to see the odules listed on a reote coputer 5via the opened P##ession9& or to iport a odule (ro a reote coputer into your coputer (or iplicit 'eoting. 'evie" the help onthose coands to learn ore.Note: Dnce you use Ne".P##ession and create your o"n persistent sessions& it is your responsibility to do housekeeping and close and dispose the session "hen you are done "ith the. 0ntil you do that& persistent sessions reain active& consue resources and ay preventothers (ro connecting. 2y de(ault& only B% siultaneous connections to a reote achine are peritted. !( you keep too any active sessions& you "ill easily run into resource liits. This line deonstrates"hat happens i( you try and set up too any siultaneous sessions:P#R B..B% T 7oreach.Db-ect O Ne".P##ession .CoputerNae C1!6NTB PRemoting Returns Deseriali,ed DataThe results you receive (ro a reote coputer have been seriali=ed into M81& and then deseriali=ed on your coputer. !n essence& the ob-ects placed into your shell)s pipeline are static& detached snapshots o( "hat "as on the reote coputer at the tie your coand copleted. These deseriali=ed ob-ects lack the ethods o( the originals ob-ects& and instead only o4er static properties.!( you need to access ethods or change properties& or in other "ords i( you ust "ork "ith the live ob-ects& siply ake sure you do so on the reote side& be(ore the ob-ects get seriali=ed and travel back to the caller. This e*aple uses ob-ect ethods on the reote side to deterine process o"ners "hich "orks -ust ,ne:P#R !nvoke.Coand .CoputerNae C1!6NTB .script2lock O Jet.WiDb-ect .Class Win/$UProcess T #elect.Db-ect Nae& O NU.JetD"ner59.0serP PDnce the results travel back to you& you can no longer invoke ob-ect ethods because no" you "ork "ith ?rehydrated@ ob-ects that are detached (ro the live ob-ects and do not contain any ethods anyore:P#R !nvoke.Coand .CoputerNae C1!6NTB .script2lock O Jet.WiDb-ect .Class Win/$UProcess P T #elect.Db-ect Nae& O NU.JetD"ner59.0ser P#eriali=ing and deseriali=ing is relatively e*pensive. 3ou can optii=e speed and resources by aking sure that your reote code eits only the data you really need. 3ou could (or e*aple use #elect.Db-ect and care(ully pick the properties you "ant back rather than seriali=ing and deseriali=ing everything.Enter"PSSession s. -no#e"%ommandA lot o( ne"coers "ill get a bit con(used about reoting& in part because o( ho" Po"er#hell e*ecutes scripts. Consider the (ollo"ing& and assue that #6'V6'$ contains a script naed C:Q'eoteTest.psB:6nter.P##ession .CoputerNae #6'V6'$C:Q'eoteTest.psB!( you "ere to sit and type these coands interactively in the console"indo" on your client coputer& this "ould "ork 5assuing reoting "as set up& you had perissions& and all that9. uest 5or& in (act& any "ay at all to do so.9 #o& go to http:AADigiCert.coAutil and do"nload their (ree certi,cate utility. 7igure$.B sho"s the utility. Note the "arning essage.7igure $.B: 1aunching DigiCert0til.e*e3ou only need to "orry about this "arning i( you plan to ac>uire your certi,cate (ro the DigiCert CA: click the 'epair button to install their interediate certi,cates on your coputer& enabling their certi,cate tobe trusted and used. 7igure $.$ sho"s the result o( doing so. Again& i( you plan to take the eventual Certi,cate 'e>uest 5C#'9 to a di4erent CA& don)t "orry about the 'epair button or the "arning essage.Note 3ou can also open a blank 88C console and add Windo"s) ?Certi,cate@ snap.in. 7ocus it on the coputer account (or the local coputer 5you)ll be propted9. Then& right.click on the ?Personal@ (older and select All Tasks to ,nd the option to create a ne" certi,cate re>uest.:7igure $.$: A(ter adding the DigiCert interediate certi,catesClick ?Create C#'.@ As sho"n in ,gure $./& ,ll in the in(oration about your organi=ation. This needs to be e*act: The ?Coon Nae@ is e*actly "hat people "ill type to access the coputer on "hich this ##1certi,cate "ill be installed. That ight be ?dca&@ in our case& or ?dc%B.ad$%%H$.loc@ i( a (ully >uali,ed nae is needed& and so on. 3our copany nae also needs to be accurate: 8ost CAs "ill veri(y this in(oration.7igure $./: 7illing in the C#'We usually save the C#' in a te*t ,le& as sho"n in ,gure $.G. 3ou can also -ust copy it to the Clipboard in any cases. When you head to your CA& ake sure you)re re>uesting an ##1 5?Web #erver&@ in soe cases9 certi,cate. An e.ail certi,cate or other type "on)t "ork.7igure $.G: #aving the C#' into a te*t ,leNe*t& take that C#' to your CA and order your certi,cate. This "ill look soething like ,gure $.L i( you)re using DigiCert: it)ll obviously be di4erent "ith another CA& "ith an internal PW!& and so (orth. Note that "ith ost coercial CAs you)ll have to select the type o( Web server you)re using: choose ?Dther&@ i( that)s an option& or ?!!#@ i( not.Note' 0sing the 8akeCert.e*e utility (ro the Windo"s #DW "ill generate a local certi,cate that only your achine "ill trust. This isn)t use(ul. 7olks tell you to do this in various blog posts because it)s >uick and easy: they also tell you to disable various security checks so that the inherently.useless certi,cate "ill "ork. !t)s a "aste o( tie. 3ou)re getting encryption& but you)ve no assurance that the reote achine is the one you intended to connect to in the ,rst place. !( soeone)s hi-acking your in(oration& "ho cares i( it "as encrypted be(ore you sent it to theV7igure $.L: 0ploading the C#' to a CA%aution' Note the "arning essage in ,gure $.L that y C#' needs to be generated "ith a $%GH.bit key. DigiCert)s utility o4ered e that& or B%$G.bit. 8any CAs "ill have a high.bit re>uireent: ake sure yourC#' coplies "ith "hat they need. Also notice that this is a Web server certi,cate "e)re applying (or: as "e "rote earlier& it)s the only kind o( certi,cate that "ill "ork.6ventually& the CA "ill issue your certi,cate. 7igure $.F sho"s "here "e "ent to do"nload it. We chose to do"nload all certi,cates: "e "anted to ensure "e had a copy o( the CA)s root certi,cate& in case "eneeded to con,gure another achine to trust that root.&ip' The trick "ith digital certi,cates is that the achine using the& and any achines they "ill be presented to& need to trust the CA that issued the certi,cate. That)s "hy you do"nload the CA root certi,cate: so you can install it on the achines that need to trust the CA. !n a large environent& this can be done via Jroup Policy& i( desired.7igure $.F: Do"nloading the issued certi,cate8ake sure you back up the certi,cate ,les; 6ven though ost CAs "ill re.issue the as needed& it)s (ar easier to have a handy backup& even on a 0#2 +ash drive.-nstalling the %erti$cateDon)t try to double.click the certi,cate ,le to install it. Doing so "ill install it into your user account)s certi,cate store: you need it in your coputer)s certi,cate store instead. To install the certi,cate& open a ne" 8icroso(t 8anageent Console 5c.e*e9& select AddA'eove #nap.ins& and add the Certi,cates snap.in& as sho"n in ,gure $.Y.7igure $.Y: Adding the Certi,cates snap.in to the 88CAs sho"n in ,gure $.H& (ocus the snap.in on the Coputer account.7igure $.H: 7ocusing the Certi,cates snap.in on the Coputer accountNe*t& as sho"n in ,gure $.I& (ocus on the local coputer. D( course& i( you)re installing a certi,cate onto a reote coputer& (ocus on that coputer instead. This is a good "ay to get a certi,cate installed onto a J0!.less #erver Core installation o( Windo"s& (or e*aple.Note' We "ish "e could sho" you a "ay to do all o( this (ro "ithin Po"er#hell. 2ut "e couldn)t ,nd one that didn)t involve a -illion ore& and ore cople*& steps. #ince this hope(ully isn)t soething you)ll have to do o(ten& or autoate a lot& the J0! is easier and should suEce.7igure $.I: 7ocusing the Certi,cates snap.in on the local coputerWith the snap.in loaded& as sho"n in ,gure $.B%& right.click the ?Personal@ store and select ?!port.@7igure $.B%: 2eginning the iport process into the Personal storeAs sho"n in ,gure $.BB& bro"se to the certi,cate ,le that you do"nloaded (ro your CA. Then& click Ne*t.%aution' !( you do"nloaded ultiple certi,cates . perhaps the CA)s root certi,cates along "ith the one issued to you . ake sure you)re iporting the ##1 certi,cate that "as issued to you. !( there)s any con(usion& #TDP. Jo back to your CA and do"nload -ust 3D0' certi,cate& so that you)ll kno" "hich one to iport. Don)t e*perient& here . you need to get this right the ,rst tie.7igure $.BB: #electing the ne"ly.issued ##1 certi,cate ,leAs sho"n in ,gure $.B$& ensure that the certi,cate "ill be placed into the Personal store.7igure $.B$: 2e sure to place the certi,cate into the Personal store& "hich should be pre.selected.As sho"n in ,gure $.B/& double.click the certi,cate to open it. Dr& right.click and select Dpen. Do not select Properties . that "on)t get you the in(oration you need.7igure $.B/: Double.click the certi,cate& or right.click and select Dpen7inally& as sho"n in ,gure $.BG& select the certi,cate)s thubprint. 3ou)ll need to either "rite this do"n& or copy it to your Clipboard. This is ho" Win'8 "ill identi(y the certi,cate you "ant to use.Note' !t)s possible to list your certi,cate in Po"er#hell)s C6'T: drive& "hich "ill ake the thubprint a bit easier to copy to the Clipboard. !nPo"er#hell& run Dir C6'T:Q1ocal8achineQ8y and read care(ully to ake sure you select the right certi,cate. !( the entire thubprint isn)t displayed& run Dir C6'T:Q1ocal8achineQ8y T 71 Z instead.7igure $.BG: Dbtaining the certi,cate)s thubprintSetting up the .&&PS /istenerThese ne*t steps "ill be accoplished in the Cd.e*e shell& not in Po"er#hell. The coand.line utility)s synta* re>uires signi,cant t"eaking and escaping in Po"er#hell& and it)s a lot easier to type and understand in the older Cd.e*e shell 5"hich is "here the utility has torun any"ay: running it in Po"er#hell "ould -ust launch Cd.e*e behindthe scenes9.As sho"n in ,gure $.BL& run the (ollo"ing coand:7igure $.BL: #etting up the uivalent Po"er#hell coand to accoplish thistask:Ne".W#8an!nstance "inrAcon,gA1istener .#elector#et \OAddressS^QZ^:TransportS^