PuTTYUserManualPuTTYisafree(MIT-licensed)WindowsTelnetandSSHclient.ThismanualdocumentsPuTTY,anditscompanionutilitiesPSCP,PSFTP,Plink,PageantandPuTTYgen.

NotetoUnixusers:thismanualcurrentlyprimarilydocumentstheWindowsversionsofthePuTTYutilities.SomeoptionsarethereforementionedthatareabsentfromtheUnixversion;theUnixversionhasfeaturesnotdescribedhere;andtheptermandcommand-lineputtygenutilitiesarenotdescribedatall.TheonlyUnix-specificdocumentationthatcurrentlyexistsisthemanpages.

Thismanualiscopyright1997-2017SimonTatham.Allrightsreserved.YoumaydistributethisdocumentationundertheMITlicence.SeeappendixCforthelicencetextinfull.

Chapter1:IntroductiontoPuTTY1.1WhatareSSH,TelnetandRlogin?1.2HowdoSSH,TelnetandRlogindiffer?

Chapter2:GettingstartedwithPuTTY2.1Startingasession2.2Verifyingthehostkey(SSHonly)2.3Loggingin2.4Afterloggingin2.5Loggingout

Chapter3:UsingPuTTY3.1Duringyoursession3.2Creatingalogfileofyoursession3.3Alteringyourcharactersetconfiguration3.4UsingX11forwardinginSSH3.5UsingportforwardinginSSH3.6MakingrawTCPconnections3.7Connectingtoalocalserialline3.8ThePuTTYcommandline

Chapter4:ConfiguringPuTTY4.1TheSessionpanel4.2TheLoggingpanel

4.3TheTerminalpanel4.4TheKeyboardpanel4.5TheBellpanel4.6TheFeaturespanel4.7TheWindowpanel4.8TheAppearancepanel4.9TheBehaviourpanel4.10TheTranslationpanel4.11TheSelectionpanel4.12TheColourspanel4.13TheConnectionpanel4.14TheDatapanel4.15TheProxypanel4.16TheTelnetpanel4.17TheRloginpanel4.18TheSSHpanel4.19TheKexpanel4.20TheHostKeyspanel4.21TheCipherpanel4.22TheAuthpanel4.23TheGSSAPIpanel4.24TheTTYpanel4.25TheX11panel4.26TheTunnelspanel4.27TheBugsandMoreBugspanels4.28TheSerialpanel4.29Storingconfigurationinafile

Chapter5:UsingPSCPtotransferfilessecurely5.1StartingPSCP5.2PSCPUsage

Chapter6:UsingPSFTPtotransferfilessecurely6.1StartingPSFTP6.2RunningPSFTP6.3UsingpublickeyauthenticationwithPSFTP

Chapter7:Usingthecommand-lineconnectiontoolPlink7.1StartingPlink7.2UsingPlink7.3UsingPlinkinbatchfilesandscripts7.4UsingPlinkwithCVS

7.5UsingPlinkwithWinCVSChapter8:UsingpublickeysforSSHauthentication

8.1Publickeyauthentication-anintroduction8.2UsingPuTTYgen,thePuTTYkeygenerator8.3Gettingreadyforpublickeyauthentication

Chapter9:UsingPageantforauthentication9.1GettingstartedwithPageant9.2ThePageantmainwindow9.3ThePageantcommandline9.4Usingagentforwarding9.5Securityconsiderations

Chapter10:Commonerrormessages10.1‘Theserver'shostkeyisnotcachedintheregistry’10.2‘WARNING-POTENTIALSECURITYBREACH!’10.3‘SSHprotocolversion2requiredbyourconfigurationbutserveronlyprovides(old,insecure)SSH-1’10.4‘Thefirstciphersupportedbytheserveris...belowtheconfiguredwarningthreshold’10.5‘Serversentdisconnectmessagetype2(protocolerror):"Toomanyauthenticationfailuresforroot"’10.6‘Outofmemory’10.7‘Internalerror’,‘Internalfault’,‘Assertionfailed’10.8‘Unabletousethisprivatekeyfile’,‘Couldn'tloadprivatekey’,‘Keyisofwrongtype’10.9‘Serverrefusedourpublickey’or‘Keyrefused’10.10‘Accessdenied’,‘Authenticationrefused’10.11‘Nosupportedauthenticationmethodsavailable’10.12‘IncorrectCRCreceivedonpacket’or‘IncorrectMACreceivedonpacket’10.13‘Incomingpacketwasgarbledondecryption’10.14‘PuTTYX11proxy:variouserrors’10.15‘Networkerror:Softwarecausedconnectionabort’10.16‘Networkerror:Connectionresetbypeer’10.17‘Networkerror:Connectionrefused’10.18‘Networkerror:Connectiontimedout’10.19‘Networkerror:Cannotassignrequestedaddress’

AppendixA:PuTTYFAQA.1IntroductionA.2FeaturessupportedinPuTTY

A.3PortstootheroperatingsystemsA.4EmbeddingPuTTYinotherprogramsA.5DetailsofPuTTY'soperationA.6HOWTOquestionsA.7TroubleshootingA.8SecurityquestionsA.9AdministrativequestionsA.10Miscellaneousquestions

AppendixB:FeedbackandbugreportingB.1GeneralguidelinesB.2ReportingbugsB.3ReportingsecurityvulnerabilitiesB.4RequestingextrafeaturesB.5RequestingfeaturesthathavealreadybeenrequestedB.6SupportrequestsB.7WebserveradministrationB.8AskingpermissionforthingsB.9MirroringthePuTTYwebsiteB.10PraiseandcomplimentsB.11E-mailaddress

AppendixC:PuTTYLicenceAppendixD:PuTTYhackingguide

D.1Cross-OSportabilityD.2MultiplebackendstreatedequallyD.3MultiplesessionsperprocessonsomeplatformsD.4C,notC++D.5Security-consciouscodingD.6IndependenceofspecificcompilerD.7SmallcodesizeD.8Single-threadedcodeD.9KeystrokessenttotheserverwhereverpossibleD.10640×480friendlinessinconfigurationpanelsD.11AutomaticallygeneratedMakefilesD.12Coroutinesinssh.cD.13SinglecompilationofeachsourcefileD.14Doaswesay,notaswedo

AppendixE:PuTTYdownloadkeysandsignaturesE.1PublickeysE.2Securitydetails

E.3KeyrolloverAppendixF:SSH-2namesspecifiedforPuTTY

F.1ConnectionprotocolchannelrequestnamesF.2KeyexchangemethodnamesF.3Encryptionalgorithmnames

Chapter1:IntroductiontoPuTTYPuTTYisafreeSSH,TelnetandRloginclientforWindowssystems.

1.1WhatareSSH,TelnetandRlogin?1.2HowdoSSH,TelnetandRlogindiffer?

1.1WhatareSSH,TelnetandRlogin?IfyoualreadyknowwhatSSH,TelnetandRloginare,youcansafelyskipontothenextsection.

SSH,TelnetandRloginarethreewaysofdoingthesamething:loggingintoamulti-usercomputerfromanothercomputer,overanetwork.

Multi-useroperatingsystems,suchasUnixandVMS,usuallypresentacommand-lineinterfacetotheuser,muchlikethe‘CommandPrompt’or‘MS-DOSPrompt’inWindows.Thesystemprintsaprompt,andyoutypecommandswhichthesystemwillobey.

Usingthistypeofinterface,thereisnoneedforyoutobesittingatthesamemachineyouaretypingcommandsto.Thecommands,andresponses,canbesentoveranetwork,soyoucansitatonecomputerandgivecommandstoanotherone,oreventomorethanone.

SSH,TelnetandRloginarenetworkprotocolsthatallowyoutodothis.Onthecomputeryousitat,yourunaclient,whichmakesanetworkconnectiontotheothercomputer(theserver).Thenetworkconnectioncarriesyourkeystrokesandcommandsfromtheclienttotheserver,andcarriestheserver'sresponsesbacktoyou.

Theseprotocolscanalsobeusedforothertypesofkeyboard-basedinteractivesession.Inparticular,therearealotofbulletinboards,talkersystemsandMUDs(Multi-UserDungeons)whichsupportaccessusingTelnet.ThereareevenafewthatsupportSSH.

YoumightwanttouseSSH,TelnetorRloginif:

youhaveanaccountonaUnixorVMSsystemwhichyouwanttobeabletoaccessfromsomewhereelseyourInternetServiceProviderprovidesyouwithaloginaccountonawebserver.(Thismightalsobeknownasashellaccount.Ashellistheprogramthatrunsontheserverandinterpretsyourcommandsforyou.)youwanttouseabulletinboardsystem,talkerorMUDwhichcanbe

accessedusingTelnet.

YouprobablydonotwanttouseSSH,TelnetorRloginif:

youonlyuseWindows.Windowscomputershavetheirownwaysofnetworkingbetweenthemselves,andunlessyouaredoingsomethingfairlyunusual,youwillnotneedtouseanyoftheseremoteloginprotocols.

1.2HowdoSSH,TelnetandRlogindiffer?ThislistsummarisessomeofthedifferencesbetweenSSH,TelnetandRlogin.

SSH(whichstandsfor‘secureshell’)isarecentlydesigned,high-securityprotocol.Itusesstrongcryptographytoprotectyourconnectionagainsteavesdropping,hijackingandotherattacks.TelnetandRloginarebotholderprotocolsofferingminimalsecurity.SSHandRloginbothallowyoutologintotheserverwithouthavingtotypeapassword.(Rlogin'smethodofdoingthisisinsecure,andcanallowanattackertoaccessyouraccountontheserver.SSH'smethodismuchmoresecure,andtypicallybreakingthesecurityrequirestheattackertohavegainedaccesstoyouractualclientmachine.)SSHallowsyoutoconnecttotheserverandautomaticallysendacommand,sothattheserverwillrunthatcommandandthendisconnect.Soyoucanuseitinautomatedprocessing.

TheInternetisahostileenvironmentandsecurityiseverybody'sresponsibility.IfyouareconnectingacrosstheopenInternet,thenwerecommendyouuseSSH.Iftheserveryouwanttoconnecttodoesn'tsupportSSH,itmightbeworthtryingtopersuadetheadministratortoinstallit.

Ifyourclientandserverarebothbehindthesame(good)firewall,itismorelikelytobesafetouseTelnetorRlogin,butwestillrecommendyouuseSSH.

Chapter2:GettingstartedwithPuTTYThischaptergivesaquickguidetothesimplesttypesofinteractiveloginsessionusingPuTTY.

2.1Startingasession2.2Verifyingthehostkey(SSHonly)2.3Loggingin2.4Afterloggingin2.5Loggingout

2.1StartingasessionWhenyoustartPuTTY,youwillseeadialogbox.ThisdialogboxallowsyoutocontroleverythingPuTTYcando.Seechapter4fordetailsofallthethingsyoucancontrol.

Youdon'tusuallyneedtochangemostoftheconfigurationoptions.Tostartthesimplestkindofsession,allyouneedtodoistoenterafewbasicparameters.

Inthe‘HostName’box,entertheInternethostnameoftheserveryouwanttoconnectto.Youshouldhavebeentoldthisbytheproviderofyourloginaccount.

Nowselectaloginprotocoltouse,fromthe‘Connectiontype’buttons.Foraloginsession,youshouldselectTelnet,RloginorSSH.Seesection1.2foradescriptionofthedifferencesbetweenthethreeprotocols,andadviceonwhichonetouse.Thefourthprotocol,Raw,isnotusedforinteractiveloginsessions;youwouldusuallyusethisfordebuggingotherInternetservices(seesection3.6).Thefifthoption,Serial,isusedforconnectingtoalocalserialline,andworkssomewhatdifferently:seesection3.7formoreinformationonthis.

Whenyouchangetheselectedprotocol,thenumberinthe‘Port’boxwillchange.Thisisnormal:ithappensbecausethevariousloginservicesareusuallyprovidedondifferentnetworkportsbytheservermachine.Mostserverswillusethestandardportnumbers,soyouwillnotneedtochangetheportsetting.Ifyourserverprovidesloginservicesonanon-standardport,yoursystemadministratorshouldhavetoldyouwhichone.(Forexample,manyMUDsrunTelnetserviceonaportotherthan23.)

Onceyouhavefilledinthe‘HostName’,‘Protocol’,andpossibly‘Port’settings,youarereadytoconnect.Pressthe‘Open’buttonatthebottomofthedialogbox,andPuTTYwillbegintryingtoconnectyoutotheserver.

2.2Verifyingthehostkey(SSHonly)IfyouarenotusingtheSSHprotocol,youcanskipthissection.

IfyouareusingSSHtoconnecttoaserverforthefirsttime,youwillprobablyseeamessagelookingsomethinglikethis:

Theserver'shostkeyisnotcachedintheregistry.You

havenoguaranteethattheserveristhecomputeryou

thinkitis.

Theserver'srsa2keyfingerprintis:

ssh-rsa10247b:e5:6f:a7:f4:f9:81:62:5c:e3:1f:bf:8b:57:6c:5a

Ifyoutrustthishost,hitYestoaddthekeyto

PuTTY'scacheandcarryonconnecting.

Ifyouwanttocarryonconnectingjustonce,without

addingthekeytothecache,hitNo.

Ifyoudonottrustthishost,hitCanceltoabandonthe

connection.

ThisisafeatureoftheSSHprotocol.Itisdesignedtoprotectyouagainstanetworkattackknownasspoofing:secretlyredirectingyourconnectiontoadifferentcomputer,sothatyousendyourpasswordtothewrongmachine.Usingthistechnique,anattackerwouldbeabletolearnthepasswordthatguardsyourloginaccount,andcouldthenloginasiftheywereyouandusetheaccountfortheirownpurposes.

Topreventthisattack,eachserverhasauniqueidentifyingcode,calledahostkey.Thesekeysarecreatedinawaythatpreventsoneserverfromforginganotherserver'skey.Soifyouconnecttoaserveranditsendsyouadifferenthostkeyfromtheoneyouwereexpecting,PuTTYcanwarnyouthattheservermayhavebeenswitchedandthataspoofingattackmightbeinprogress.

PuTTYrecordsthehostkeyforeachserveryouconnectto,intheWindowsRegistry.Everytimeyouconnecttoaserver,itchecksthatthehostkeypresentedbytheserveristhesamehostkeyasitwasthelasttimeyouconnected.Ifitisnot,youwillseeawarning,andyouwillhavethechancetoabandonyourconnectionbeforeyoutypeanyprivateinformation(suchasapassword)intoit.

However,whenyouconnecttoaserveryouhavenotconnectedto

before,PuTTYhasnowayoftellingwhetherthehostkeyistherightoneornot.Soitgivesthewarningshownabove,andasksyouwhetheryouwanttotrustthishostkeyornot.

Whetherornottotrustthehostkeyisyourchoice.Ifyouareconnectingwithinacompanynetwork,youmightfeelthatallthenetworkusersareonthesamesideandspoofingattacksareunlikely,soyoumightchoosetotrustthekeywithoutcheckingit.Ifyouareconnectingacrossahostilenetwork(suchastheInternet),youshouldcheckwithyoursystemadministrator,perhapsbytelephoneorinperson.(Manyservershavemorethanonehostkey.Ifthesystemadministratorsendsyoumorethanonefingerprint,youshouldmakesuretheonePuTTYshowsyouisonthelist,butitdoesn'tmatterwhichoneitis.)

Seesection4.20foradvancedoptionsformanaginghostkeys.

2.3LogginginAfteryouhaveconnected,andperhapsverifiedtheserver'shostkey,youwillbeaskedtologin,probablyusingausernameandapassword.Yoursystemadministratorshouldhaveprovidedyouwiththese.Entertheusernameandthepassword,andtheservershouldgrantyouaccessandbeginyoursession.Ifyouhavemistypedyourpassword,mostserverswillgiveyouseveralchancestogetitright.

IfyouareusingSSH,becarefulnottotypeyourusernamewrongly,becauseyouwillnothaveachancetocorrectitafteryoupressReturn;manySSHserversdonotpermityoutomaketwologinattemptsusingdifferentusernames.Ifyoutypeyourusernamewrongly,youmustclosePuTTYandstartagain.

Ifyourpasswordisrefusedbutyouaresureyouhavetypeditcorrectly,checkthatCapsLockisnotenabled.Manyloginservers,particularlyUnixcomputers,treatuppercaseandlowercaseasdifferentwhencheckingyourpassword;soifCapsLockison,yourpasswordwillprobablyberefused.

2.4AfterlogginginAfteryoulogintotheserver,whathappensnextisuptotheserver!Mostserverswillprintsomesortofloginmessageandthenpresentaprompt,atwhichyoucantypecommandswhichtheserverwillcarryout.Someserverswillofferyouon-linehelp;othersmightnot.Ifyouareindoubtaboutwhattodonext,consultyoursystemadministrator.

2.5LoggingoutWhenyouhavefinishedyoursession,youshouldlogoutbytypingtheserver'sownlogoutcommand.Thismightvarybetweenservers;ifindoubt,trylogoutorexit,orconsultamanualoryoursystemadministrator.Whentheserverprocessesyourlogoutcommand,thePuTTYwindowshouldcloseitselfautomatically.

YoucancloseaPuTTYsessionusingtheClosebuttoninthewindowborder,butthismightconfusetheserver-abitlikehangingupatelephoneunexpectedlyinthemiddleofaconversation.Werecommendyoudonotdothisunlesstheserverhasstoppedrespondingtoyouandyoucannotclosethewindowanyotherway.

Chapter3:UsingPuTTYThischapterprovidesageneralintroductiontosomemoreadvancedfeaturesofPuTTY.Forextremedetailandreferencepurposes,chapter4islikelytocontainmoreinformation.

3.1Duringyoursession3.1.1Copyingandpastingtext3.1.2Scrollingthescreenback3.1.3TheSystemmenu

3.2Creatingalogfileofyoursession3.3Alteringyourcharactersetconfiguration3.4UsingX11forwardinginSSH3.5UsingportforwardinginSSH3.6MakingrawTCPconnections3.7Connectingtoalocalserialline3.8ThePuTTYcommandline

3.8.1Startingasessionfromthecommandline3.8.2-cleanup3.8.3Standardcommand-lineoptions

3.1DuringyoursessionAlotofPuTTY'scomplexityandfeaturesareintheconfigurationpanel.Onceyouhaveworkedyourwaythroughthatandstartedasession,thingsshouldbereasonablysimpleafterthat.Nevertheless,thereareafewmoreusefulfeaturesavailable.

3.1.1Copyingandpastingtext3.1.2Scrollingthescreenback3.1.3TheSystemmenu

3.1.3.1ThePuTTYEventLog3.1.3.2Specialcommands3.1.3.3Startingnewsessions3.1.3.4Changingyoursessionsettings3.1.3.5CopyAlltoClipboard3.1.3.6Clearingandresettingtheterminal3.1.3.7Fullscreenmode

3.1.1CopyingandpastingtextOfteninaPuTTYsessionyouwillfindtextonyourterminalscreenwhichyouwanttotypeinagain.Likemostotherterminalemulators,PuTTYallowsyoutocopyandpastethetextratherthanhavingtotypeitagain.Also,copyandpasteusestheWindowsclipboard,sothatyoucanpaste(forexample)URLsintoawebbrowser,orpastefromawordprocessororspreadsheetintoyourterminalsession.

PuTTY'scopyandpasteworksentirelywiththemouse.Inordertocopytexttotheclipboard,youjustclicktheleftmousebuttonintheterminalwindow,anddragtoselecttext.Whenyouletgoofthebutton,thetextisautomaticallycopiedtotheclipboard.YoudonotneedtopressCtrl-CorCtrl-Ins;infact,ifyoudopressCtrl-C,PuTTYwillsendaCtrl-Ccharacterdownyoursessiontotheserverwhereitwillprobablycauseaprocesstobeinterrupted.

Pastingisdoneusingtherightbutton(orthemiddlemousebutton,ifyouhaveathree-buttonmouseandhavesetitup;seesection4.11.2).(PressingShift-Ins,orselecting‘Paste’fromtheCtrl+right-clickcontextmenu,havethesameeffect.)Whenyouclicktherightmousebutton,PuTTYwillreadwhateverisintheWindowsclipboardandpasteitintoyoursession,exactlyasifithadbeentypedatthekeyboard.(Therefore,becarefulofpastingformattedtextintoaneditorthatdoesautomaticindenting;youmayfindthatthespacespastedfromtheclipboardplusthespacesaddedbytheeditoradduptotoomanyspacesandruintheformatting.ThereisnothingPuTTYcandoaboutthis.)

Ifyoudouble-clicktheleftmousebutton,PuTTYwillselectawholeword.Ifyoudouble-click,holddownthesecondclick,anddragthemouse,PuTTYwillselectasequenceofwholewords.(YoucanadjustpreciselywhatPuTTYconsiderstobepartofaword;seesection4.11.5.)Ifyoutriple-click,ortriple-clickanddrag,thenPuTTYwillselectawholelineorsequenceoflines.

Ifyouwanttoselectarectangularregioninsteadofselectingtotheendofeachline,youcandothisbyholdingdownAltwhenyoumakeyourselection.Youcanalsoconfigurerectangularselectiontobethedefault,

andthenholdingdownAltgivesthenormalbehaviourinstead:seesection4.11.4fordetails.

(InsomeUnixenvironments,Alt+dragisinterceptedbythewindowmanager.Shift+Alt+dragshouldworkforrectangularselectionaswell,soyoucouldtrythatinstead.)

Ifyouhaveamiddlemousebutton,thenyoucanuseittoadjustanexistingselectionifyouselectedsomethingslightlywrong.(Ifyouhaveconfiguredthemiddlemousebuttontopaste,thentherightmousebuttondoesthisinstead.)Clickthebuttononthescreen,andyoucanpickupthenearestendoftheselectionanddragittosomewhereelse.

It'spossiblefortheservertoasktohandlemouseclicksinthePuTTYwindowitself.Ifthishappens,themousepointerwillturnintoanarrow,andusingthemousetocopyandpastewillonlyworkifyouholddownShift.Seesection4.6.2andsection4.11.3fordetailsofthisfeatureandhowtoconfigureit.

3.1.2ScrollingthescreenbackPuTTYkeepstrackoftextthathasscrolledupoffthetopoftheterminal.Soifsomethingappearsonthescreenthatyouwanttoread,butitscrollstoofastandit'sgonebythetimeyoutrytolookforit,youcanusethescrollbarontherightsideofthewindowtolookbackupthesessionhistoryandfinditagain.

Aswellasusingthescrollbar,youcanalsopagethescrollbackupanddownbypressingShift-PgUpandShift-PgDn.YoucanscrollalineatatimeusingCtrl-PgUpandCtrl-PgDn.Thesearestillavailableifyouconfigurethescrollbartobeinvisible.

Bydefaultthelast2000linesscrolledoffthetoparepreservedforyoutolookat.Youcanincrease(ordecrease)thisvalueusingtheconfigurationbox;seesection4.7.3.

3.1.3TheSystemmenuIfyouclicktheleftmousebuttonontheiconinthetopleftcornerofPuTTY'sterminalwindow,orclicktherightmousebuttononthetitlebar,youwillseethestandardWindowssystemmenucontainingitemslikeMinimise,Move,SizeandClose.

PuTTY'ssystemmenucontainsextraprogramfeaturesinadditiontotheWindowsstandardoptions.Theseextramenucommandsaredescribedbelow.

(TheseoptionsarealsoavailableinacontextmenubroughtupbyholdingCtrlandclickingwiththerightmousebuttonanywhereinthePuTTYwindow.)

3.1.3.1ThePuTTYEventLog3.1.3.2Specialcommands3.1.3.3Startingnewsessions3.1.3.4Changingyoursessionsettings3.1.3.5CopyAlltoClipboard3.1.3.6Clearingandresettingtheterminal3.1.3.7Fullscreenmode

3.1.3.1ThePuTTYEventLogIfyouchoose‘EventLog’fromthesystemmenu,asmallwindowwillpopupinwhichPuTTYlogssignificanteventsduringtheconnection.Mostoftheeventsinthelogwillprobablytakeplaceduringsessionstartup,butafewcanoccuratanypointinthesession,andoneortwooccurrightattheend.

YoucanusethemousetoselectoneormorelinesoftheEventLog,andhittheCopybuttontocopythemtotheclipboard.Ifyouarereportingabug,it'softenusefultopastethecontentsoftheEventLogintoyourbugreport.

(TheEventLogisnotthesameasthefacilitytocreatealogfileofyoursession;that'sdescribedinsection3.2.)

3.1.3.2SpecialcommandsDependingontheprotocolusedforthecurrentsession,theremaybeasubmenuof‘specialcommands’.Theseareprotocol-specifictokens,suchasa‘break’signal,thatcanbesentdownaconnectioninadditiontonormaldata.Theirpreciseeffectisusuallyuptotheserver.CurrentlyonlyTelnet,SSH,andserialconnectionshavespecialcommands.

The‘break’signalcanalsobeinvokedfromthekeyboardwithCtrl-Break.

ThefollowingspecialcommandsareavailableinTelnet:

AreYouThereBreakSynchEraseCharacter

PuTTYcanalsobeconfiguredtosendthiswhentheBackspacekeyispressed;seesection4.16.3.

EraseLineGoAheadNoOperation

Shouldhavenoeffect.

AbortProcessAbortOutputInterruptProcess

PuTTYcanalsobeconfiguredtosendthiswhenCtrl-Cistyped;seesection4.16.3.

SuspendProcess

PuTTYcanalsobeconfiguredtosendthiswhenCtrl-Zistyped;seesection4.16.3.

EndOfRecord

EndOfFile

InanSSHconnection,thefollowingspecialcommandsareavailable:

IGNOREmessage

Shouldhavenoeffect.

Repeatkeyexchange

OnlyavailableinSSH-2.Forcesarepeatkeyexchangeimmediately(andresetsassociatedtimersandcounters).Formoreinformationaboutrepeatkeyexchanges,seesection4.19.2.

Cachenewhostkeytype

OnlyavailableinSSH-2.ThissubmenuappearsonlyiftheserverhashostkeysofatypethatPuTTYdoesn'talreadyhavecached,andsowon'tconsider.SelectingakeyherewillallowPuTTYtousethatkeynowandinfuture:PuTTYwilldoafreshkey-exchangewiththeselectedkey,andimmediatelyaddthatkeytoitspermanentcache(relyingonthehostkeyusedatthestartoftheconnectiontocross-certifythenewkey).Thatkeywillbeusedfortherestofthecurrentsession;itmaynotactuallybeusedforfuturesessions,dependingonyourpreferences(seesection4.20.1).

Normally,PuTTYwillcarryonusingahostkeyitalreadyknows,eveniftheserverofferskeyformatsthatPuTTYwouldotherwiseprefer,toavoidhostkeyprompts.Asaresult,ifyou'vebeenusingaserverforsomeyears,youmaystillbeusinganolderkeythananewuserwoulduse,duetoserverupgradesinthemeantime.TheSSHprotocolunfortunatelydoesnothaveorganisedfacilitiesforhostkeymigrationandrollover,butthisallowsyoutomanuallyupgrade.

Break

OnlyavailableinSSH-2,andonlyduringasession.Optionalextension;maynotbesupportedbyserver.PuTTYrequeststheserver'sdefaultbreaklength.

Signals(SIGINT,SIGTERMetc)

OnlyavailableinSSH-2,andonlyduringasession.SendsvariousPOSIXsignals.Nothonouredbyallservers.

Withaserialconnection,theonlyavailablespecialcommandis‘Break’.

3.1.3.3StartingnewsessionsPuTTY'ssystemmenuprovidessomeshortcutwaystostartnewsessions:

Selecting‘NewSession’willstartacompletelynewinstanceofPuTTY,andbringuptheconfigurationboxasnormal.Selecting‘DuplicateSession’willstartasessioninanewwindowwithpreciselythesameoptionsasyourcurrentone-connectingtothesamehostusingthesameprotocol,withallthesameterminalsettingsandeverything.Inaninactivewindow,selecting‘RestartSession’willdothesameas‘DuplicateSession’,butinthecurrentwindow.The‘SavedSessions’submenugivesyouquickaccesstoanysetsofstoredsessiondetailsyouhavepreviouslysaved.Seesection4.1.2fordetailsofhowtocreatesavedsessions.

3.1.3.4ChangingyoursessionsettingsIfyouselect‘ChangeSettings’fromthesystemmenu,PuTTYwilldisplayacut-downversionofitsinitialconfigurationbox.Thisallowsyoutoadjustmostpropertiesofyourcurrentsession.Youcanchangetheterminalsize,thefont,theactionsofvariouskeypresses,thecolours,andsoon.

Someoftheoptionsthatareavailableinthemainconfigurationboxarenotshowninthecut-downChangeSettingsbox.Theseareusuallyoptionswhichdon'tmakesensetochangeinthemiddleofasession(forexample,youcan'tswitchfromSSHtoTelnetinmid-session).

Youcansavethecurrentsettingstoasavedsessionforfutureusefromthisdialogbox.Seesection4.1.2formoreonsavedsessions.

3.1.3.5CopyAlltoClipboardThissystemmenuoptionprovidesaconvenientwaytocopythewholecontentsoftheterminalscreen(uptothelastnonemptyline)andscrollbacktotheclipboardinonego.

3.1.3.6ClearingandresettingtheterminalThe‘ClearScrollback’optiononthesystemmenutellsPuTTYtodiscardallthelinesoftextthathavebeenkeptaftertheyscrolledoffthetopofthescreen.Thismightbeuseful,forexample,ifyoudisplayedsensitiveinformationandwantedtomakesurenobodycouldlookoveryourshoulderandseeit.(Notethatthisonlypreventsacasualuserfromusingthescrollbartoviewtheinformation;thetextisnotguaranteednottostillbeinPuTTY'smemory.)

The‘ResetTerminal’optioncausesafullresetoftheterminalemulation.AVT-seriesterminalisacomplexpieceofsoftwareandcaneasilygetintoastatewhereallthetextprintedbecomesunreadable.(Thiscanhappen,forexample,ifyouaccidentallyoutputabinaryfiletoyourterminal.)Ifthishappens,selectingResetTerminalshouldsortitout.

3.1.3.7FullscreenmodeIfyoufindthetitlebaronamaximisedwindowtobeuglyordistracting,youcanselectFullScreenmodetomaximisePuTTY‘evenmore’.Whenyouselectthis,PuTTYwillexpandtofillthewholescreenanditsborders,titlebarandscrollbarwilldisappear.(Youcanconfigurethescrollbarnottodisappearinfull-screenmodeifyouwanttokeepit;seesection4.7.3.)

Whenyouareinfull-screenmode,youcanstillaccessthesystemmenuifyouclicktheleftmousebuttonintheextremetopleftcornerofthescreen.

3.2CreatingalogfileofyoursessionForsomepurposesyoumayfindyouwanttologeverythingthatappearsonyourscreen.Youcandothisusingthe‘Logging’panelintheconfigurationbox.

Tobeginasessionlog,select‘ChangeSettings’fromthesystemmenuandgototheLoggingpanel.Enteralogfilename,andselectaloggingmode.(Youcanlogallsessionoutputincludingtheterminalcontrolsequences,oryoucanjustlogtheprintabletext.Itdependswhatyouwantthelogfor.)Click‘Apply’andyourlogwillbestarted.Lateron,youcangobacktotheLoggingpanelandselect‘Loggingturnedoffcompletely’tostoplogging;thenPuTTYwillclosethelogfileandyoucansafelyreadit.

Seesection4.2formoredetailsandoptions.

3.3AlteringyourcharactersetconfigurationIfyoufindthatspecialcharacters(accentedcharacters,forexample,orline-drawingcharacters)arenotbeingdisplayedcorrectlyinyourPuTTYsession,itmaybethatPuTTYisinterpretingthecharacterssentbytheserveraccordingtothewrongcharacterset.Therearealotofdifferentcharactersetsavailable,andnogoodwayforPuTTYtoknowwhichtouse,soit'sentirelypossibleforthistohappen.

Ifyouclick‘ChangeSettings’andlookatthe‘Translation’panel,youshouldseealargenumberofcharactersetswhichyoucanselect,andotherrelatedoptions.Nowallyouneedistofindoutwhichofthemyouwant!(Seesection4.10formoreinformation.)

3.4UsingX11forwardinginSSHTheSSHprotocolhastheabilitytosecurelyforwardXWindowSystemgraphicalapplicationsoveryourencryptedSSHconnection,sothatyoucanrunanapplicationontheSSHservermachineandhaveitputitswindowsuponyourlocalmachinewithoutsendinganyXnetworktrafficintheclear.

Inordertousethisfeature,youwillneedanXdisplayserverforyourWindowsmachine,suchasCygwin/X,X-Win32,orExceed.Thiswillprobablyinstallitselfasdisplaynumber0onyourlocalmachine;ifitdoesn't,themanualfortheXservershouldtellyouwhatitdoesdo.

Youshouldthentickthe‘EnableX11forwarding’boxintheX11panel(seesection4.25)beforestartingyourSSHsession.The‘Xdisplaylocation’boxisblankbydefault,whichmeansthatPuTTYwilltrytouseasensibledefaultsuchas:0,whichistheusualdisplaylocationwhereyourXserverwillbeinstalled.Ifthatneedschanging,thenchangeit.

NowyoushouldbeabletologintotheSSHserverasnormal.TocheckthatXforwardinghasbeensuccessfullynegotiatedduringconnectionstartup,youcancheckthePuTTYEventLog(seesection3.1.3.1).Itshouldsaysomethinglikethis:

2001-12-0517:22:01RequestingX11forwarding

2001-12-0517:22:02X11forwardingenabled

IftheremotesystemisUnixorUnix-like,youshouldalsobeabletoseethattheDISPLAYenvironmentvariablehasbeensettopointatdisplay10oraboveontheSSHservermachineitself:

fred@unixbox:~$echo$DISPLAY

unixbox:10.0

Ifthisworks,youshouldthenbeabletorunXapplicationsintheremotesessionandhavethemdisplaytheirwindowsonyourPC.

FormoreoptionsrelatingtoX11forwarding,seesection4.25.

3.5UsingportforwardinginSSHTheSSHprotocolhastheabilitytoforwardarbitrarynetwork(TCP)connectionsoveryourencryptedSSHconnection,toavoidthenetworktrafficbeingsentinclear.Forexample,youcouldusethistoconnectfromyourhomecomputertoaPOP-3serveronaremotemachinewithoutyourPOP-3passwordbeingvisibletonetworksniffers.

Inordertouseportforwardingtoconnectfromyourlocalmachinetoaportonaremoteserver,youneedto:

ChooseaportnumberonyourlocalmachinewherePuTTYshouldlistenforincomingconnections.Therearelikelytobeplentyofunusedportnumbersabove3000.(Youcanalsousealocalloopbackaddresshere;seebelowformoredetails.)Now,beforeyoustartyourSSHconnection,gototheTunnelspanel(seesection4.26).Makesurethe‘Local’radiobuttonisset.Enterthelocalportnumberintothe‘Sourceport’box.Enterthedestinationhostnameandportnumberintothe‘Destination’box,separatedbyacolon(forexample,popserver.example.com:110toconnecttoaPOP-3server).Nowclickthe‘Add’button.Thedetailsofyourportforwardingshouldappearinthelistbox.

Nowstartyoursessionandlogin.(Portforwardingwillnotbeenableduntilafteryouhaveloggedin;otherwiseitwouldbeeasytoperformcompletelyanonymousnetworkattacks,andgainaccesstoanyone'svirtualprivatenetwork.)TocheckthatPuTTYhassetuptheportforwardingcorrectly,youcanlookatthePuTTYEventLog(seesection3.1.3.1).Itshouldsaysomethinglikethis:

2001-12-0517:22:10Localport3110forwardingto

popserver.example.com:110

NowifyouconnecttothesourceportnumberonyourlocalPC,youshouldfindthatitanswersyouexactlyasifitweretheservicerunningonthedestinationmachine.Sointhisexample,youcouldthenconfigureane-mailclienttouselocalhost:3110asaPOP-3serverinsteadofpopserver.example.com:110.(Ofcourse,theforwardingwillstop

happeningwhenyourPuTTYsessionclosesdown.)

Youcanalsoforwardportsintheotherdirection:arrangeforaparticularportnumberontheservermachinetobeforwardedbacktoyourPCasaconnectiontoaserviceonyourPCornearit.Todothis,justselectthe‘Remote’radiobuttoninsteadofthe‘Local’one.The‘Sourceport’boxwillnowspecifyaportnumberontheserver(notethatmostserverswillnotallowyoutouseportnumbersunder1024forthispurpose).

AnalternativewaytoforwardlocalconnectionstoremotehostsistousedynamicSOCKSproxying.Inthismode,PuTTYactsasaSOCKSserver,whichSOCKS-awareprogramscanconnecttoandopenforwardedconnectionstothedestinationoftheirchoice,sothiscanbeanalternativetolonglistsofstaticforwardings.Tousethismode,youwillneedtoselectthe‘Dynamic’radiobuttoninsteadof‘Local’,andthenyoushouldnotenteranythingintothe‘Destination’box(itwillbeignored).PuTTYwillthenlistenforSOCKSconnectionsontheportyouhavespecified.MostwebbrowserscanbeconfiguredtoconnecttothisSOCKSproxyservice;also,youcanforwardotherPuTTYconnectionsthroughitbysettinguptheProxycontrolpanel(seesection4.15fordetails).

ThesourceportforaforwardedconnectionusuallydoesnotacceptconnectionsfromanymachineexcepttheSSHclientorservermachineitself(forlocalandremoteforwardingsrespectively).TherearecontrolsintheTunnelspaneltochangethis:

The‘Localportsacceptconnectionsfromotherhosts’optionallowsyoutosetuplocal-to-remoteportforwardings(includingdynamicportforwardings)insuchawaythatmachinesotherthanyourclientPCcanconnecttotheforwardedport.The‘Remoteportsdothesame’optiondoesthesamethingforremote-to-localportforwardings(sothatmachinesotherthantheSSHservermachinecanconnecttotheforwardedport.)NotethatthisfeatureisonlyavailableintheSSH-2protocol,andnotallSSH-2servershonourit(inOpenSSH,forexample,it'susuallydisabledbydefault).

YoucanalsospecifyanIPaddresstolistenon.TypicallyaWindows

machinecanbeaskedtolistenonanysingleIPaddressinthe127.*.*.*range,andalloftheseareloopbackaddressesavailableonlytothelocalmachine.Soifyouforward(forexample)127.0.0.5:79toaremotemachine'sfingerport,thenyoushouldbeabletoruncommandssuchasfingerfred@127.0.0.5.Thiscanbeusefuliftheprogramconnectingtotheforwardedportdoesn'tallowyoutochangetheportnumberituses.Thisfeatureisavailableforlocal-to-remoteforwardedports;SSH-1isunabletosupportitforremote-to-localports,whileSSH-2cansupportitintheorybutserverswillnotnecessarilycooperate.

(Notethatifyou'reusingWindowsXPServicePack2,youmayneedtoobtainafixfromMicrosoftinordertouseaddresseslike127.0.0.5-seequestionA.7.17.)

Formoreoptionsrelatingtoportforwarding,seesection4.26.

IftheconnectionyouareforwardingoverSSHisitselfasecondSSHconnectionmadebyanothercopyofPuTTY,youmightfindthe‘logicalhostname’configurationoptionusefultowarnPuTTYofwhichhostkeyitshouldbeexpecting.Seesection4.13.5fordetailsofthis.

3.6MakingrawTCPconnectionsAlotofInternetprotocolsarecomposedofcommandsandresponsesinplaintext.Forexample,SMTP(theprotocolusedtotransfere-mail),NNTP(theprotocolusedtotransferUsenetnews),andHTTP(theprotocolusedtoserveWebpages)allconsistofcommandsinreadableplaintext.

Sometimesitcanbeusefultoconnectdirectlytooneoftheseservicesandspeaktheprotocol‘byhand’,bytypingprotocolcommandsandwatchingtheresponses.OnUnixmachines,youcandothisusingthesystem'stelnetcommandtoconnecttotherightportnumber.Forexample,telnetmailserver.example.com25mightenableyoutotalkdirectlytotheSMTPservicerunningonamailserver.

AlthoughtheUnixtelnetprogramprovidesthisfunctionality,theprotocolbeingusedisnotreallyTelnet.Reallythereisnoactualprotocolatall;thebytessentdowntheconnectionareexactlytheonesyoutype,andthebytesshownonthescreenareexactlytheonessentbytheserver.UnixtelnetwillattempttodetectorguesswhethertheserviceitistalkingtoisarealTelnetserviceornot;PuTTYpreferstobetoldforcertain.

Inordertomakeadebuggingconnectiontoaserviceofthistype,yousimplyselectthefourthprotocolname,‘Raw’,fromthe‘Protocol’buttonsinthe‘Session’configurationpanel.(Seesection4.1.1.)Youcanthenenterahostnameandaportnumber,andmaketheconnection.

3.7ConnectingtoalocalseriallinePuTTYcanconnectdirectlytoalocalseriallineasanalternativetomakinganetworkconnection.Inthismode,texttypedintothePuTTYwindowwillbesentstraightoutofyourcomputer'sserialport,anddatareceivedthroughthatportwillbedisplayedinthePuTTYwindow.Youmightusethismode,forexample,ifyourserialportisconnectedtoanothercomputerwhichhasaserialconnection.

Tomakeaconnectionofthistype,simplyselect‘Serial’fromthe‘Connectiontype’radiobuttonsonthe‘Session’configurationpanel(seesection4.1.1).The‘HostName’and‘Port’boxeswilltransforminto‘Serialline’and‘Speed’,allowingyoutospecifywhichseriallinetouse(ifyourcomputerhasmorethanone)andwhatspeed(baudrate)tousewhentransferringdata.Forfurtherconfigurationoptions(databits,stopbits,parity,flowcontrol),youcanusethe‘Serial’configurationpanel(seesection4.28).

AfteryoustartupPuTTYinserialmode,youmightfindthatyouhavetomakethefirstmove,bysendingsomedataoutoftheseriallineinordertonotifythedeviceattheotherendthatsomeoneisthereforittotalkto.Thisprobablydependsonthedevice.IfyoustartupaPuTTYserialsessionandnothingappearsinthewindow,trypressingReturnafewtimesandseeifthathelps.

Aseriallineprovidesnowelldefinedmeansforoneendoftheconnectiontonotifytheotherthattheconnectionisfinished.Therefore,PuTTYinserialmodewillremainconnecteduntilyouclosethewindowusingtheclosebutton.

3.8ThePuTTYcommandlinePuTTYcanbemadetodovariousthingswithoutuserinterventionbysupplyingcommand-linearguments(e.g.,fromacommandpromptwindow,oraWindowsshortcut).

3.8.1Startingasessionfromthecommandline3.8.2-cleanup3.8.3Standardcommand-lineoptions

3.8.3.1-load:loadasavedsession3.8.3.2Selectingaprotocol:-ssh,-telnet,-rlogin,-raw-serial

3.8.3.3-v:increaseverbosity3.8.3.4-l:specifyaloginname3.8.3.5-L,-Rand-D:setupportforwardings3.8.3.6-m:readaremotecommandorscriptfromafile3.8.3.7-P:specifyaportnumber3.8.3.8-pw:specifyapassword3.8.3.9-agentand-noagent:controluseofPageantforauthentication3.8.3.10-Aand-a:controlagentforwarding3.8.3.11-Xand-x:controlX11forwarding3.8.3.12-tand-T:controlpseudo-terminalallocation3.8.3.13-N:suppressstartingashellorcommand3.8.3.14-nc:makearemotenetworkconnectioninplaceofaremoteshellorcommand3.8.3.15-C:enablecompression3.8.3.16-1and-2:specifyanSSHprotocolversion3.8.3.17-4and-6:specifyanInternetprotocolversion3.8.3.18-i:specifyanSSHprivatekey3.8.3.19-loghost:specifyalogicalhostname3.8.3.20-hostkey:manuallyspecifyanexpectedhostkey3.8.3.21-pgpfp:displayPGPkeyfingerprints3.8.3.22-sercfg:specifyserialportconfiguration3.8.3.23-sessionlog,-sshlog,-sshrawlog:specifysessionlogging3.8.3.24-proxycmd:specifyalocalproxycommand3.8.3.25-restrict-acl:restricttheWindowsprocessACL

3.8.1StartingasessionfromthecommandlineTheseoptionsallowyoutobypasstheconfigurationwindowandlaunchstraightintoasession.

Tostartaconnectiontoaservercalledhost:

putty.exe[-ssh|-telnet|-rlogin|-raw][user@]host

Ifthissyntaxisused,settingsaretakenfromtheDefaultSettings(seesection4.1.2);useroverridesthesesettingsifsupplied.Also,youcanspecifyaprotocol,whichwilloverridethedefaultprotocol(seesection3.8.3.2).

Fortelnetsessions,thefollowingalternativesyntaxissupported(thismakesPuTTYsuitableforuseasaURLhandlerfortelnetURLsinwebbrowsers):

putty.exetelnet://host[:port]/

Tostartaconnectiontoaserialport,e.g.COM1:

putty.exe-serialcom1

Inordertostartanexistingsavedsessioncalledsessionname,usethe-loadoption(describedinsection3.8.3.1).

putty.exe-load"sessionname"

3.8.2-cleanupIfinvokedwiththe-cleanupoption,ratherthanrunningasnormal,PuTTYwillremoveitsregistryentriesandrandomseedfilefromthelocalmachine(afterconfirmingwiththeuser).Itwillalsoattempttoremoveinformationaboutrecentlylaunchedsessionsstoredinthe‘jumplist’onWindows7andup.

Notethatonmulti-usersystems,-cleanuponlyremovesregistryentriesandfilesassociatedwiththecurrentlylogged-inuser.

3.8.3Standardcommand-lineoptionsPuTTYanditsassociatedtoolssupportarangeofcommand-lineoptions,mostofwhichareconsistentacrossallthetools.Thissectionliststheavailableoptionsinalltools.Optionswhicharespecifictoaparticulartoolarecoveredinthechapteraboutthattool.

3.8.3.1-load:loadasavedsession3.8.3.2Selectingaprotocol:-ssh,-telnet,-rlogin,-raw-serial3.8.3.3-v:increaseverbosity3.8.3.4-l:specifyaloginname3.8.3.5-L,-Rand-D:setupportforwardings3.8.3.6-m:readaremotecommandorscriptfromafile3.8.3.7-P:specifyaportnumber3.8.3.8-pw:specifyapassword3.8.3.9-agentand-noagent:controluseofPageantforauthentication3.8.3.10-Aand-a:controlagentforwarding3.8.3.11-Xand-x:controlX11forwarding3.8.3.12-tand-T:controlpseudo-terminalallocation3.8.3.13-N:suppressstartingashellorcommand3.8.3.14-nc:makearemotenetworkconnectioninplaceofaremoteshellorcommand3.8.3.15-C:enablecompression3.8.3.16-1and-2:specifyanSSHprotocolversion3.8.3.17-4and-6:specifyanInternetprotocolversion3.8.3.18-i:specifyanSSHprivatekey3.8.3.19-loghost:specifyalogicalhostname3.8.3.20-hostkey:manuallyspecifyanexpectedhostkey3.8.3.21-pgpfp:displayPGPkeyfingerprints3.8.3.22-sercfg:specifyserialportconfiguration3.8.3.23-sessionlog,-sshlog,-sshrawlog:specifysessionlogging3.8.3.24-proxycmd:specifyalocalproxycommand3.8.3.25-restrict-acl:restricttheWindowsprocessACL

3.8.3.1-load:loadasavedsessionThe-loadoptioncausesPuTTYtoloadconfigurationdetailsoutofasavedsession.Ifthesedetailsincludeahostname,thenthisoptionisallyouneedtomakePuTTYstartasession.

Youneeddoublequotesaroundthesessionnameifitcontainsspaces.

IfyouwanttocreateaWindowsshortcuttostartaPuTTYsavedsession,thisistheoptionyoushoulduse:yourshortcutshouldcallsomethinglike

d:\path\to\putty.exe-load"mysession"

(NotethatPuTTYitselfsupportsanalternativeformofthisoption,forbackwardscompatibility.Ifyouexecuteputty@sessionnameitwillhavethesameeffectasputty-load"sessionname".Withthe@form,nodoublequotesarerequired,andthe@signmustbetheveryfirstthingonthecommandline.Thisformoftheoptionisdeprecated.)

3.8.3.2Selectingaprotocol:-ssh,-telnet,-rlogin,-raw-serialTochoosewhichprotocolyouwanttoconnectwith,youcanuseoneoftheseoptions:

-sshselectstheSSHprotocol.-telnetselectstheTelnetprotocol.-rloginselectstheRloginprotocol.-rawselectstherawprotocol.-serialselectsaserialconnection.

TheseoptionsarenotavailableinthefiletransfertoolsPSCPandPSFTP(whichonlyworkwiththeSSHprotocol).

TheseoptionsareequivalenttotheprotocolselectionbuttonsintheSessionpanelofthePuTTYconfigurationbox(seesection4.1.1).

3.8.3.3-v:increaseverbosityMostofthePuTTYtoolscanbemadetotellyoumoreaboutwhattheyaredoingbysupplyingthe-voption.Ifyouarehavingtroublewhenmakingaconnection,oryou'resimplycurious,youcanturnthisswitchonandhopetofindoutmoreaboutwhatishappening.

3.8.3.4-l:specifyaloginnameYoucanspecifytheusernametologinasontheremoteserverusingthe-loption.Forexample,plinklogin.example.com-lfred.

TheseoptionsareequivalenttotheusernameselectionboxintheConnectionpanelofthePuTTYconfigurationbox(seesection4.14.1).

3.8.3.5-L,-Rand-D:setupportforwardingsAswellassettingupportforwardingsinthePuTTYconfiguration(seesection4.26),youcanalsosetupforwardingsonthecommandline.Thecommand-lineoptionsworkjustliketheonesinUnixsshprograms.

Toforwardalocalport(say5110)toaremotedestination(saypopserver.example.comport110),youcanwritesomethinglikeoneofthese:

putty-L5110:popserver.example.com:110-loadmysession

plinkmysession-L5110:popserver.example.com:110

Toforwardaremoteporttoalocaldestination,justusethe-Roptioninsteadof-L:

putty-R5023:mytelnetserver.myhouse.org:23-loadmysession

plinkmysession-R5023:mytelnetserver.myhouse.org:23

TospecifyanIPaddressforthelisteningendofthetunnel,prependittotheargument:

plink-L127.0.0.5:23:localhost:23myhost

TosetupSOCKS-baseddynamicportforwardingonalocalport,usethe-Doption.Forthisoneyouonlyhavetopasstheportnumber:

putty-D4096-loadmysession

Forgeneralinformationonportforwarding,seesection3.5.

TheseoptionsarenotavailableinthefiletransfertoolsPSCPandPSFTP.

3.8.3.6-m:readaremotecommandorscriptfromafileThe-moptionperformsasimilarfunctiontothe‘Remotecommand’boxintheSSHpanelofthePuTTYconfigurationbox(seesection4.18.1).However,the-moptionexpectstobegivenalocalfilename,anditwillreadacommandfromthatfile.

Withsomeservers(particularlyUnixsystems),youcanevenputmultiplelinesinthisfileandexecutemorethanonecommandinsequence,orawholeshellscript;butthisisarguablyanabuse,andcannotbeexpectedtoworkonallservers.Inparticular,itisknownnottoworkwithcertain‘embedded’servers,suchasCiscorouters.

ThisoptionisnotavailableinthefiletransfertoolsPSCPandPSFTP.

3.8.3.7-P:specifyaportnumberThe-Poptionisusedtospecifytheportnumbertoconnectto.IfyouhaveaTelnetserverrunningonport9696ofamachineinsteadofport23,forexample:

putty-telnet-P9696host.name

plink-telnet-P9696host.name

(NotethatthisoptionismoreusefulinPlinkthaninPuTTY,becauseinPuTTYyoucanwriteputty-telnethost.name9696inanycase.)

ThisoptionisequivalenttotheportnumbercontrolintheSessionpanelofthePuTTYconfigurationbox(seesection4.1.1).

3.8.3.8-pw:specifyapasswordAsimplewaytoautomatearemoteloginistosupplyyourpasswordonthecommandline.Thisisnotrecommendedforreasonsofsecurity.Ifyoupossiblycan,werecommendyousetuppublic-keyauthenticationinstead.Seechapter8fordetails.

Notethatthe-pwoptiononlyworkswhenyouareusingtheSSHprotocol.DuetofundamentallimitationsofTelnetandRlogin,theseprotocolsdonotsupportautomatedpasswordauthentication.

3.8.3.9-agentand-noagent:controluseofPageantforauthenticationThe-agentoptionturnsonSSHauthenticationusingPageant,and-noagentturnsitoff.TheseoptionsareonlymeaningfulifyouareusingSSH.

Seechapter9forgeneralinformationonPageant.

TheseoptionsareequivalenttotheagentauthenticationcheckboxintheAuthpanelofthePuTTYconfigurationbox(seesection4.22.3).

3.8.3.10-Aand-a:controlagentforwardingThe-AoptionturnsonSSHagentforwarding,and-aturnsitoff.TheseoptionsareonlymeaningfulifyouareusingSSH.

Seechapter9forgeneralinformationonPageant,andsection9.4forinformationonagentforwarding.Notethatthereisasecurityriskinvolvedwithenablingthisoption;seesection9.5fordetails.

TheseoptionsareequivalenttotheagentforwardingcheckboxintheAuthpanelofthePuTTYconfigurationbox(seesection4.22.6).

TheseoptionsarenotavailableinthefiletransfertoolsPSCPandPSFTP.

3.8.3.11-Xand-x:controlX11forwardingThe-XoptionturnsonX11forwardinginSSH,and-xturnsitoff.TheseoptionsareonlymeaningfulifyouareusingSSH.

ForinformationonX11forwarding,seesection3.4.

TheseoptionsareequivalenttotheX11forwardingcheckboxintheX11panelofthePuTTYconfigurationbox(seesection4.25).

TheseoptionsarenotavailableinthefiletransfertoolsPSCPandPSFTP.

3.8.3.12-tand-T:controlpseudo-terminalallocationThe-toptionensuresPuTTYattemptstoallocateapseudo-terminalattheserver,and-Tstopsitfromallocatingone.TheseoptionsareonlymeaningfulifyouareusingSSH.

Theseoptionsareequivalenttothe‘Don'tallocateapseudo-terminal’checkboxintheSSHpanelofthePuTTYconfigurationbox(seesection4.24.1).

TheseoptionsarenotavailableinthefiletransfertoolsPSCPandPSFTP.

3.8.3.13-N:suppressstartingashellorcommandThe-NoptionpreventsPuTTYfromattemptingtostartashellorcommandontheremoteserver.YoumightwanttousethisoptionifyouareonlyusingtheSSHconnectionforportforwarding,andyouruseraccountontheserverdoesnothavetheabilitytorunashell.

ThisfeatureisonlyavailableinSSHprotocolversion2(sincetheversion1protocolassumesyouwillalwayswanttorunashell).

Thisoptionisequivalenttothe‘Don'tstartashellorcommandatall’checkboxintheSSHpanelofthePuTTYconfigurationbox(seesection4.18.2).

ThisoptionisnotavailableinthefiletransfertoolsPSCPandPSFTP.

3.8.3.14-nc:makearemotenetworkconnectioninplaceofaremoteshellorcommandThe-ncoptionpreventsPlink(orPuTTY)fromattemptingtostartashellorcommandontheremoteserver.Instead,itwillinstructtheremoteservertoopenanetworkconnectiontoahostnameandportnumberspecifiedbyyou,andtreatthatnetworkconnectionasifitwerethemainsession.

Youspecifyahostandportasanargumenttothe-ncoption,withacolonseparatingthehostnamefromtheportnumber,likethis:

plinkhost1.example.com-nchost2.example.com:1234

YoumightwanttousethisfeatureifyouneededtomakeanSSHconnectiontoatargethostwhichyoucanonlyreachbygoingthroughaproxyhost,andratherthanusingportforwardingyouprefertousethelocalproxyfeature(seesection4.15.1formoreaboutlocalproxies).Inthissituationyoumightselect‘Local’proxytype,setyourlocalproxycommandtobe‘plink%proxyhost-nc%host:%port’,enterthetargethostnameontheSessionpanel,andenterthedirectlyreachableproxyhostnameontheProxypanel.

ThisfeatureisonlyavailableinSSHprotocolversion2(sincetheversion1protocolassumesyouwillalwayswanttorunashell).ItisnotavailableinthefiletransfertoolsPSCPandPSFTP.ItisavailableinPuTTYitself,althoughitisunlikelytobeveryusefulinanytoolotherthanPlink.Also,-ncusesthesameserverfunctionalityasportforwarding,soitwillnotworkifyourserveradministratorhasdisabledportforwarding.

(Theoptionisnamed-ncaftertheUnixprogramnc,shortfor‘netcat’.Thecommand‘plinkhost1-nchost2:port’isverysimilarinfunctionalityto‘plinkhost1nchost2port’,whichinvokesncontheserverandtellsittoconnecttothespecifieddestination.However,Plink'sbuilt-in-ncoptiondoesnotdependonthencprogrambeinginstalledontheserver.)

3.8.3.15-C:enablecompressionThe-Coptionenablescompressionofthedatasentacrossthenetwork.ThisoptionisonlymeaningfulifyouareusingSSH.

Thisoptionisequivalenttothe‘Enablecompression’checkboxintheSSHpanelofthePuTTYconfigurationbox(seesection4.18.3).

3.8.3.16-1and-2:specifyanSSHprotocolversionThe-1and-2optionsforcePuTTYtouseversion1orversion2oftheSSHprotocol.TheseoptionsareonlymeaningfulifyouareusingSSH.

TheseoptionsareequivalenttoselectingtheSSHprotocolversionintheSSHpanelofthePuTTYconfigurationbox(seesection4.18.4).

3.8.3.17-4and-6:specifyanInternetprotocolversionThe-4and-6optionsforcePuTTYtousetheolderInternetprotocolIPv4orthenewerIPv6formostoutgoingconnections.

TheseoptionsareequivalenttoselectingyourpreferredInternetprotocolversionas‘IPv4’or‘IPv6’intheConnectionpanelofthePuTTYconfigurationbox(seesection4.13.4).

3.8.3.18-i:specifyanSSHprivatekeyThe-ioptionallowsyoutospecifythenameofaprivatekeyfilein*.PPKformatwhichPuTTYwillusetoauthenticatewiththeserver.ThisoptionisonlymeaningfulifyouareusingSSH.

IfyouareusingPageant,youcanalsospecifyapublickeyfile(inRFC4716orOpenSSHformat)toidentifyaspecifickeyfiletouse.(Thiswon'tworkifyou'renotrunningPageant,ofcourse.)

Forgeneralinformationonpublic-keyauthentication,seechapter8.

Thisoptionisequivalenttothe‘Privatekeyfileforauthentication’boxintheAuthpanelofthePuTTYconfigurationbox(seesection4.22.8).

3.8.3.19-loghost:specifyalogicalhostnameThisoptionoverridesPuTTY'snormalSSHhostkeycachingpolicybytellingitthenameofthehostyouexpectyourconnectiontoendupat(incaseswherethisdiffersfromthelocationPuTTYthinksit'sconnectingto).Itcanbeaplainhostname,orahostnamefollowedbyacolonandaportnumber.Seesection4.13.5formoredetailonthis.

3.8.3.20-hostkey:manuallyspecifyanexpectedhostkeyThisoptionoverridesPuTTY'snormalSSHhostkeycachingpolicybytellingitexactlywhathostkeytoexpect,whichcanbeusefulifthenormalautomatichostkeystoreintheRegistryisunavailable.Theargumenttothisoptionshouldbeeitherahostkeyfingerprint,oranSSH-2publickeyblob.Seesection4.20.2formoreinformation.

Youcanspecifythisoptionmorethanonceifyouwanttoconfiguremorethanonekeytobeaccepted.

3.8.3.21-pgpfp:displayPGPkeyfingerprintsThisoptioncausesthePuTTYtoolsnottorunasnormal,butinsteadtodisplaythefingerprintsofthePuTTYPGPMasterKeys,inordertoaidwithverifyingnewversions.SeeappendixEformoreinformation.

3.8.3.22-sercfg:specifyserialportconfigurationThisoptionspecifiestheconfigurationparametersfortheserialport(baudrate,stopbitsetc).Itsargumentisinterpretedasacomma-separatedlistofconfigurationoptions,whichcanbeasfollows:

Anysingledigitfrom5to9setsthenumberofdatabits.‘1’,‘1.5’or‘2’setsthenumberofstopbits.Anyothernumericstringisinterpretedasabaudrate.Asinglelower-caseletterspecifiestheparity:‘n’fornone,‘o’forodd,‘e’foreven,‘m’formarkand‘s’forspace.Asingleupper-caseletterspecifiestheflowcontrol:‘N’fornone,‘X’forXON/XOFF,‘R’forRTS/CTSand‘D’forDSR/DTR.

Forexample,‘-sercfg19200,8,n,1,N’denotesabaudrateof19200,8databits,noparity,1stopbitandnoflowcontrol.

3.8.3.23-sessionlog,-sshlog,-sshrawlog:specifysessionloggingTheseoptionscausethePuTTYnetworktoolstowriteoutalogfile.Eachofthemexpectsafilenameasanargument,e.g.‘-sshlogputty.log’causesanSSHpacketlogtobewrittentoafilecalled‘putty.log’.Thethreedifferentoptionsselectdifferentloggingmodes,allavailablefromtheGUItoo:

-sessionlogselects‘Allsessionoutput’loggingmode.-sshlogselects‘SSHpackets’loggingmode.-sshrawlogselects‘SSHpacketsandrawdata’loggingmode.

Formoreinformationonloggingconfiguration,seesection4.2.

3.8.3.24-proxycmd:specifyalocalproxycommandThisoptionenablesPuTTY'smodeforrunningacommandonthelocalmachineandusingitasaproxyforthenetworkconnection.Itexpectsashellcommandstringasanargument.

Seesection4.15.1formoreinformationonthis,andonotherproxysettings.Inparticular,notethatsincethespecialsequencesdescribedthereareunderstoodintheargumentstring,literalbackslashesmustbedoubled(ifyouwant\inyourcommand,youmustput\\onthecommandline).

3.8.3.25-restrict-acl:restricttheWindowsprocessACLThisoption(onWindowsonly)causesPuTTY(oranotherPuTTYtool)totrytolockdowntheoperatingsystem'saccesscontrolonitsownprocess.Ifthissucceeds,itshouldpresentanextraobstacletomalwarethathasmanagedtorununderthesameuseridasthePuTTYprocess,bypreventingitfromattachingtoPuTTYusingthesameinterfacesdebuggersuseandeitherreadingsensitiveinformationoutofitsmemoryorhijackingitsnetworksession.

Thisoptionisnotenabledbydefault,becausethisformofinteractionbetweenWindowsprogramshasmanylegitimateuses,includingaccessibilitysoftwaresuchasscreenreaders.Also,itcannotprovidefullsecurityagainstthisclassofattackinanycase,becausePuTTYcanonlylockdownitsownACLafterithasstartedup,andmalwarecouldstillgetinifitattackstheprocessbetweenstartupandlockdown.Soittradesawaynoticeableconvenience,anddeliverslessrealsecuritythanyoumightwant.However,ifyoudowanttomakethattradeoffanyway,theoptionisavailable.

APuTTYprocessstartedwith-restrict-aclwillpassthatontoanyprocessesstartedwithDuplicateSession,NewSessionetc.(However,ifyou'reinvokingPuTTYtoolsexplicitly,forinstanceasaproxycommand,you'llneedtoarrangetopassthemthe-restrict-acloptionyourself,ifthat'swhatyouwant.)

Chapter4:ConfiguringPuTTYThischapterdescribesalltheconfigurationoptionsinPuTTY.

PuTTYisconfiguredusingthecontrolpanelthatcomesupbeforeyoustartasession.Someoptionscanalsobechangedinthemiddleofasession,byselecting‘ChangeSettings’fromthewindowmenu.

4.1TheSessionpanel4.1.1Thehostnamesection4.1.2Loadingandstoringsavedsessions4.1.3‘CloseWindowonExit’

4.2TheLoggingpanel4.2.1‘Logfilename’4.2.2‘Whattodoifthelogfilealreadyexists’4.2.3‘Flushlogfilefrequently’4.2.4OptionsspecifictoSSHpacketlogging

4.3TheTerminalpanel4.3.1‘Autowrapmodeinitiallyon’4.3.2‘DECOriginModeinitiallyon’4.3.3‘ImplicitCRineveryLF’4.3.4‘ImplicitLFineveryCR’4.3.5‘Usebackgroundcolourtoerasescreen’4.3.6‘Enableblinkingtext’4.3.7‘Answerbackto^E’4.3.8‘Localecho’4.3.9‘Locallineediting’4.3.10Remote-controlledprinting

4.4TheKeyboardpanel4.4.1ChangingtheactionoftheBackspacekey4.4.2ChangingtheactionoftheHomeandEndkeys4.4.3Changingtheactionofthefunctionkeysandkeypad4.4.4ControllingApplicationCursorKeysmode4.4.5ControllingApplicationKeypadmode4.4.6UsingNetHackkeypadmode4.4.7EnablingaDEC-likeComposekey4.4.8‘Control-AltisdifferentfromAltGr’

4.5TheBellpanel

4.5.1‘Setthestyleofbell’4.5.2‘Taskbar/captionindicationonbell’4.5.3‘Controlthebelloverloadbehaviour’

4.6TheFeaturespanel4.6.1Disablingapplicationkeypadandcursorkeys4.6.2Disablingxterm-stylemousereporting4.6.3Disablingremoteterminalresizing4.6.4Disablingswitchingtothealternatescreen4.6.5Disablingremotewindowtitlechanging4.6.6Responsetoremotewindowtitlequerying4.6.7Disablingremotescrollbackclearing4.6.8Disablingdestructivebackspace4.6.9Disablingremotecharactersetconfiguration4.6.10DisablingArabictextshaping4.6.11Disablingbidirectionaltextdisplay

4.7TheWindowpanel4.7.1SettingthesizeofthePuTTYwindow4.7.2Whattodowhenthewindowisresized4.7.3Controllingscrollback4.7.4‘Pusherasedtextintoscrollback’

4.8TheAppearancepanel4.8.1Controllingtheappearanceofthecursor4.8.2Controllingthefontusedintheterminalwindow4.8.3‘Hidemousepointerwhentypinginwindow’4.8.4Controllingthewindowborder

4.9TheBehaviourpanel4.9.1Controllingthewindowtitle4.9.2‘Warnbeforeclosingwindow’4.9.3‘WindowclosesonALT-F4’4.9.4‘SystemmenuappearsonALT-Space’4.9.5‘SystemmenuappearsonAltalone’4.9.6‘Ensurewindowisalwaysontop’4.9.7‘FullscreenonAlt-Enter’

4.10TheTranslationpanel4.10.1Controllingcharactersettranslation4.10.2‘TreatCJKambiguouscharactersaswide’4.10.3‘CapsLockactsasCyrillicswitch’4.10.4Controllingdisplayofline-drawingcharacters4.10.5Controllingcopyandpasteoflinedrawingcharacters

4.11TheSelectionpanel4.11.1PastinginRichTextFormat4.11.2Changingtheactionsofthemousebuttons4.11.3‘Shiftoverridesapplication'suseofmouse’4.11.4Defaultselectionmode4.11.5Configuringword-by-wordselection

4.12TheColourspanel4.12.1‘AllowterminaltospecifyANSIcolours’4.12.2‘Allowterminaltousexterm256-colourmode’4.12.3‘Indicateboldedtextbychanging...’4.12.4‘Attempttouselogicalpalettes’4.12.5‘Usesystemcolours’4.12.6Adjustingthecoloursintheterminalwindow

4.13TheConnectionpanel4.13.1Usingkeepalivestopreventdisconnection4.13.2‘DisableNagle'salgorithm’4.13.3‘EnableTCPkeepalives’4.13.4‘Internetprotocol’4.13.5‘Logicalnameofremotehost’

4.14TheDatapanel4.14.1‘Auto-loginusername’4.14.2Useofsystemusername4.14.3‘Terminal-typestring’4.14.4‘Terminalspeeds’4.14.5Settingenvironmentvariablesontheserver

4.15TheProxypanel4.15.1Settingtheproxytype4.15.2Excludingpartsofthenetworkfromproxying4.15.3Nameresolutionwhenusingaproxy4.15.4Usernameandpassword4.15.5SpecifyingtheTelnetorLocalproxycommand4.15.6Controllingproxylogging

4.16TheTelnetpanel4.16.1‘HandlingofOLD_ENVIRONambiguity’4.16.2PassiveandactiveTelnetnegotiationmodes4.16.3‘KeyboardsendsTelnetspecialcommands’4.16.4‘ReturnkeysendsTelnetNewLineinsteadof^M’

4.17TheRloginpanel4.17.1‘Localusername’

4.18TheSSHpanel4.18.1Executingaspecificcommandontheserver4.18.2‘Don'tstartashellorcommandatall’4.18.3‘Enablecompression’4.18.4‘SSHprotocolversion’4.18.5SharinganSSHconnectionbetweenPuTTYtools

4.19TheKexpanel4.19.1Keyexchangealgorithmselection4.19.2Repeatkeyexchange

4.20TheHostKeyspanel4.20.1Hostkeytypeselection4.20.2Manuallyconfiguringhostkeys

4.21TheCipherpanel4.22TheAuthpanel

4.22.1‘Displaypre-authenticationbanner’4.22.2‘Bypassauthenticationentirely’4.22.3‘AttemptauthenticationusingPageant’4.22.4‘AttemptTISorCryptoCardauthentication’4.22.5‘Attemptkeyboard-interactiveauthentication’4.22.6‘Allowagentforwarding’4.22.7‘AllowattemptedchangesofusernameinSSH-2’4.22.8‘Privatekeyfileforauthentication’

4.23TheGSSAPIpanel4.23.1‘AllowGSSAPIcredentialdelegation’4.23.2PreferenceorderforGSSAPIlibraries

4.24TheTTYpanel4.24.1‘Don'tallocateapseudo-terminal’4.24.2Sendingterminalmodes

4.25TheX11panel4.25.1RemoteX11authentication4.25.2Xauthorityfileforlocaldisplay

4.26TheTunnelspanel4.26.1Controllingthevisibilityofforwardedports4.26.2SelectingInternetprotocolversionforforwardedports

4.27TheBugsandMoreBugspanels4.27.1‘ChokesonSSH-1ignoremessages’4.27.2‘RefusesallSSH-1passwordcamouflage’4.27.3‘ChokesonSSH-1RSAauthentication’4.27.4‘ChokesonSSH-2ignoremessages’

4.27.5‘ChokesonPuTTY'sSSH-2‘winadj’requests’4.27.6‘MiscomputesSSH-2HMACkeys’4.27.7‘MiscomputesSSH-2encryptionkeys’4.27.8‘RequirespaddingonSSH-2RSAsignatures’4.27.9‘MisusesthesessionIDinSSH-2PKauth’4.27.10‘HandlesSSH-2keyre-exchangebadly’4.27.11‘IgnoresSSH-2maximumpacketsize’4.27.12‘Repliestorequestsonclosedchannels’4.27.13‘Onlysupportspre-RFC4419SSH-2DHGEX’

4.28TheSerialpanel4.28.1Selectingaseriallinetoconnectto4.28.2Selectingthespeedofyourserialline4.28.3Selectingthenumberofdatabits4.28.4Selectingthenumberofstopbits4.28.5Selectingtheserialparitycheckingscheme4.28.6Selectingtheserialflowcontrolscheme

4.29Storingconfigurationinafile

4.1TheSessionpanelTheSessionconfigurationpanelcontainsthebasicoptionsyouneedtospecifyinordertoopenasessionatall,andalsoallowsyoutosaveyoursettingstobereloadedlater.

4.1.1Thehostnamesection4.1.2Loadingandstoringsavedsessions4.1.3‘CloseWindowonExit’

4.1.1ThehostnamesectionThetopboxontheSessionpanel,labelled‘Specifyyourconnectionbyhostname’,containsthedetailsthatneedtobefilledinbeforePuTTYcanopenasessionatall.

The‘HostName’boxiswhereyoutypethename,ortheIPaddress,oftheserveryouwanttoconnectto.The‘Connectiontype’radiobuttonsletyouchoosewhattypeofconnectionyouwanttomake:arawconnection,aTelnetconnection,anRloginconnection,anSSHconnection,oraconnectiontoalocalserialline.(Seesection1.2forasummaryofthedifferencesbetweenSSH,Telnetandrlogin;seesection3.6foranexplanationof‘raw’connections;seesection3.7forinformationaboutusingaserialline.)The‘Port’boxletsyouspecifywhichportnumberontheservertoconnectto.IfyouselectTelnet,Rlogin,orSSH,thisboxwillbefilledinautomaticallytotheusualvalue,andyouwillonlyneedtochangeitifyouhaveanunusualserver.IfyouselectRawmode,youwillalmostcertainlyneedtofillinthe‘Port’boxyourself.

Ifyouselect‘Serial’fromthe‘Connectiontype’radiobuttons,the‘HostName’and‘Port’boxesarereplacedby‘Serialline’and‘Speed’;seesection4.28formoredetailsofthese.

4.1.2LoadingandstoringsavedsessionsThenextpartoftheSessionconfigurationpanelallowsyoutosaveyourpreferredPuTTYoptionssotheywillappearautomaticallythenexttimeyoustartPuTTY.Italsoallowsyoutocreatesavedsessions,whichcontainafullsetofconfigurationoptionsplusahostnameandprotocol.AsavedsessioncontainsalltheinformationPuTTYneedstostartexactlythesessionyouwant.

Tosaveyourdefaultsettings:firstsetupthesettingsthewayyouwantthemsaved.ThencomebacktotheSessionpanel.Selectthe‘DefaultSettings’entryinthesavedsessionslist,withasingleclick.Thenpressthe‘Save’button.

Ifthereisaspecifichostyouwanttostorethedetailsofhowtoconnectto,youshouldcreateasavedsession,whichwillbeseparatefromtheDefaultSettings.

Tosaveasession:firstgothroughtherestoftheconfigurationboxsettingupalltheoptionsyouwant.ThencomebacktotheSessionpanel.Enteranameforthesavedsessioninthe‘SavedSessions’inputbox.(Theservernameisoftenagoodchoiceforasavedsessionname.)Thenpressthe‘Save’button.Yoursavedsessionnameshouldnowappearinthelistbox.

Youcanalsosavesettingsinmid-session,fromthe‘ChangeSettings’dialog.Settingschangedsincethestartofthesessionwillbesavedwiththeircurrentvalues;aswellassettingschangedthroughthedialog,thisincludeschangesinwindowsize,windowtitlechangessentbytheserver,andsoon.

Toreloadasavedsession:single-clicktoselectthesessionnameinthelistbox,andthenpressthe‘Load’button.Yoursavedsettingsshouldallappearintheconfigurationpanel.Tomodifyasavedsession:firstloaditasdescribedabove.Thenmakethechangesyouwant.ComebacktotheSessionpanel,andpressthe‘Save’button.Thenewsettingswillbesavedoverthetopoftheoldones.

Tosavethenewsettingsunderadifferentname,youcanenterthenewnameinthe‘SavedSessions’box,orsingle-clicktoselectasessionnameinthelistboxtooverwritethatsession.Tosave‘DefaultSettings’,youmustsingle-clickthenamebeforesaving.

Tostartasavedsessionimmediately:double-clickonthesessionnameinthelistbox.Todeleteasavedsession:single-clicktoselectthesessionnameinthelistbox,andthenpressthe‘Delete’button.

EachsavedsessionisindependentoftheDefaultSettingsconfiguration.IfyouchangeyourpreferencesandupdateDefaultSettings,youmustalsoupdateeverysavedsessionseparately.

SavedsessionsarestoredintheRegistry,atthelocation

HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\Sessions

Ifyouneedtostoretheminafile,youcouldtrythemethoddescribedinsection4.29.

4.1.3‘CloseWindowonExit’FinallyintheSessionpanel,thereisanoptionlabelled‘CloseWindowonExit’.ThiscontrolswhetherthePuTTYterminalwindowdisappearsassoonasthesessioninsideitterminates.Ifyouarelikelytowanttocopyandpastetextoutofthesessionafterithasterminated,orrestartthesession,youshouldarrangeforthisoptiontobeoff.

‘CloseWindowOnExit’hasthreesettings.‘Always’meansalwaysclosethewindowonexit;‘Never’meansnevercloseonexit(alwaysleavethewindowopen,butinactive).Thethirdsetting,andthedefaultone,is‘Onlyoncleanexit’.Inthismode,asessionwhichterminatesnormallywillcauseitswindowtoclose,butonewhichisabortedunexpectedlybynetworktroubleoraconfusingmessagefromtheserverwillleavethewindowup.

4.2TheLoggingpanelTheLoggingconfigurationpanelallowsyoutosavelogfilesofyourPuTTYsessions,fordebugging,analysisorfuturereference.

Themainoptionisaradio-buttonsetthatspecifieswhetherPuTTYwillloganythingatall.Theoptionsare:

‘None’.Thisisthedefaultoption;inthismodePuTTYwillnotcreatealogfileatall.‘Printableoutput’.Inthismode,alogfilewillbecreatedandwrittento,butonlyprintabletextwillbesavedintoit.Thevariousterminalcontrolcodesthataretypicallysentdownaninteractivesessionalongsidetheprintabletextwillbeomitted.Thismightbeausefulmodeifyouwanttoreadalogfileinatexteditorandhopetobeabletomakesenseofit.‘Allsessionoutput’.Inthismode,everythingsentbytheserverintoyourterminalsessionislogged.Ifyouviewthelogfileinatexteditor,therefore,youmaywellfinditfullofstrangecontrolcharacters.ThisisaparticularlyusefulmodeifyouareexperiencingproblemswithPuTTY'sterminalhandling:youcanrecordeverythingthatwenttotheterminal,sothatsomeoneelsecanreplaythesessionlaterinslowmotionandwatchtoseewhatwentwrong.‘SSHpackets’.Inthismode(whichisonlyusedbySSHconnections),theSSHmessagepacketssentovertheencryptedconnectionarewrittentothelogfile(aswellasEventLogentries).Youmightneedthistodebuganetwork-levelproblem,ormorelikelytosendtothePuTTYauthorsaspartofabugreport.BEWARNEDthatifyouloginusingapassword,thepasswordcanappearinthelogfile;seesection4.2.4foroptionsthatmayhelptoremovesensitivematerialfromthelogfilebeforeyousendittoanyoneelse.‘SSHpacketsandrawdata’.Inthismode,aswellasthedecryptedpackets(asinthepreviousmode),theraw(encrypted,compressed,etc)packetsarealsologged.Thiscouldbeusefultodiagnosecorruptionintransit.(Thesamecaveatsasthepreviousmodeapply,ofcourse.)

Notethatthenon-SSHloggingoptions(‘Printableoutput’and‘Allsession

output’)onlyworkwithPuTTYproper;inprogramswithoutterminalemulation(suchasPlink),theywillhavenoeffect,evenifenabledviasavedsettings.

4.2.1‘Logfilename’4.2.2‘Whattodoifthelogfilealreadyexists’4.2.3‘Flushlogfilefrequently’4.2.4OptionsspecifictoSSHpacketlogging

4.2.4.1‘Omitknownpasswordfields’4.2.4.2‘Omitsessiondata’

4.2.1‘Logfilename’Inthiseditboxyouenterthenameofthefileyouwanttologthesessionto.The‘Browse’buttonwillletyoulookaroundyourfilesystemtofindtherightplacetoputthefile;orifyoualreadyknowexactlywhereyouwantittogo,youcanjusttypeapathnameintotheeditbox.

Thereareafewspecialfeaturesinthisbox.Ifyouusethe&characterinthefilenamebox,PuTTYwillinsertdetailsofthecurrentsessioninthenameofthefileitactuallyopens.Theprecisereplacementsitwilldoare:

&Ywillbereplacedbythecurrentyear,asfourdigits.&Mwillbereplacedbythecurrentmonth,astwodigits.&Dwillbereplacedbythecurrentdayofthemonth,astwodigits.&Twillbereplacedbythecurrenttime,assixdigits(HHMMSS)withnopunctuation.&Hwillbereplacedbythehostnameyouareconnectingto.&Pwillbereplacedbytheportnumberyouareconnectingtoonthetargethost.

Forexample,ifyouenterthehostnamec:\puttylogs\log-&h-&y&m&d-&t.dat,youwillendupwithfileslookinglike

log-server1.example.com-20010528-110859.dat

log-unixbox.somewhere.org-20010611-221001.dat

4.2.2‘Whattodoifthelogfilealreadyexists’ThiscontrolallowsyoutospecifywhatPuTTYshoulddoifittriestostartwritingtoalogfileanditfindsthefilealreadyexists.Youmightwanttoautomaticallydestroytheexistinglogfileandstartanewonewiththesamename.Alternatively,youmightwanttoopentheexistinglogfileandadddatatotheendofit.Finally(thedefaultoption),youmightnotwanttohaveanyautomaticbehaviour,buttoasktheusereverytimetheproblemcomesup.

4.2.3‘Flushlogfilefrequently’Thisoptionallowsyoutocontrolhowfrequentlyloggeddataisflushedtodisc.Bydefault,PuTTYwillflushdataassoonasitisdisplayed,sothatifyouviewthelogfilewhileasessionisstillopen,itwillbeuptodate;andiftheclientsystemcrashes,there'sagreaterchancethatthedatawillbepreserved.

However,thiscanincuraperformancepenalty.IfPuTTYisrunningslowlywithloggingenabled,youcouldtryuncheckingthisoption.Bewarnedthatthelogfilemaynotalwaysbeuptodateasaresult(althoughitwillofcoursebeflushedwhenitisclosed,forinstanceattheendofasession).

4.2.4OptionsspecifictoSSHpacketloggingTheseoptionsonlyapplyifSSHpacketdataisbeinglogged.

Thefollowingoptionsallowparticularlysensitiveportionsofunencryptedpacketstobeautomaticallyleftoutofthelogfile.Theyareonlyintendedtodetercasualnosiness;anattackercouldgleanalotofusefulinformationfromeventheseobfuscatedlogs(e.g.,lengthofpassword).

4.2.4.1‘Omitknownpasswordfields’4.2.4.2‘Omitsessiondata’

4.2.4.1‘Omitknownpasswordfields’Whenchecked,decryptedpasswordfieldsareremovedfromthelogoftransmittedpackets.(Thisincludesanyuserresponsestochallenge-responseauthenticationmethodssuchas‘keyboard-interactive’.)ThisdoesnotincludeX11authenticationdataifusingX11forwarding.

NotethatthiswillonlyomitdatathatPuTTYknowstobeapassword.However,ifyoustartanotherloginsessionwithinyourPuTTYsession,forinstance,anypasswordusedwillappearintheclearinthepacketlog.Thenextoptionmaybeofusetoprotectagainstthis.

Thisoptionisenabledbydefault.

4.2.4.2‘Omitsessiondata’Whenchecked,alldecrypted‘sessiondata’isomitted;thisisdefinedasdatainterminalsessionsandinforwardedchannels(TCP,X11,andauthenticationagent).Thiswillusuallysubstantiallyreducethesizeoftheresultinglogfile.

Thisoptionisdisabledbydefault.

4.3TheTerminalpanelTheTerminalconfigurationpanelallowsyoutocontrolthebehaviourofPuTTY'sterminalemulation.

4.3.1‘Autowrapmodeinitiallyon’4.3.2‘DECOriginModeinitiallyon’4.3.3‘ImplicitCRineveryLF’4.3.4‘ImplicitLFineveryCR’4.3.5‘Usebackgroundcolourtoerasescreen’4.3.6‘Enableblinkingtext’4.3.7‘Answerbackto^E’4.3.8‘Localecho’4.3.9‘Locallineediting’4.3.10Remote-controlledprinting

4.3.1‘Autowrapmodeinitiallyon’AutowrapmodecontrolswhathappenswhentextprintedinaPuTTYwindowreachestheright-handedgeofthewindow.

Withautowrapmodeon,ifalonglineoftextreachestheright-handedge,itwillwrapoverontothenextlinesoyoucanstillseeallthetext.Withautowrapmodeoff,thecursorwillstayattheright-handedgeofthescreen,andallthecharactersinthelinewillbeprintedontopofeachother.

Ifyouarerunningafull-screenapplicationandyouoccasionallyfindthescreenscrollingupwhenitlooksasifitshouldn't,youcouldtryturningthisoptionoff.

Autowrapmodecanbeturnedonandoffbycontrolsequencessentbytheserver.Thisconfigurationoptioncontrolsthedefaultstate,whichwillberestoredwhenyouresettheterminal(seesection3.1.3.6).However,ifyoumodifythisoptioninmid-sessionusing‘ChangeSettings’,itwilltakeeffectimmediately.

4.3.2‘DECOriginModeinitiallyon’DECOriginModeisaminoroptionwhichcontrolshowPuTTYinterpretscursor-positioncontrolsequencessentbytheserver.

Theservercansendacontrolsequencethatrestrictsthescrollingregionofthedisplay.Forexample,inaneditor,theservermightreservealineatthetopofthescreenandalineatthebottom,andmightsendacontrolsequencethatcausesscrollingoperationstoaffectonlytheremaininglines.

WithDECOriginModeon,cursorcoordinatesarecountedfromthetopofthescrollingregion.Withitturnedoff,cursorcoordinatesarecountedfromthetopofthewholescreenregardlessofthescrollingregion.

Itisunlikelyyouwouldneedtochangethisoption,butifyoufindafull-screenapplicationisdisplayingpiecesoftextinwhatlookslikethewrongpartofthescreen,youcouldtryturningDECOriginModeontoseewhetherthathelps.

DECOriginModecanbeturnedonandoffbycontrolsequencessentbytheserver.Thisconfigurationoptioncontrolsthedefaultstate,whichwillberestoredwhenyouresettheterminal(seesection3.1.3.6).However,ifyoumodifythisoptioninmid-sessionusing‘ChangeSettings’,itwilltakeeffectimmediately.

4.3.3‘ImplicitCRineveryLF’Mostserverssendtwocontrolcharacters,CRandLF,tostartanewlineofthescreen.TheCRcharactermakesthecursorreturntotheleft-handsideofthescreen.TheLFcharactermakesthecursormoveonelinedown(andmightmakethescreenscroll).

SomeserversonlysendLF,andexpecttheterminaltomovethecursorovertotheleftautomatically.Ifyoucomeacrossaserverthatdoesthis,youwillseeasteppedeffectonthescreen,likethis:

Firstlineoftext

Secondline

Thirdline

Ifthishappenstoyou,tryenablingthe‘ImplicitCRineveryLF’option,andthingsmightgobacktonormal:

Firstlineoftext

Secondline

Thirdline

4.3.4‘ImplicitLFineveryCR’Mostserverssendtwocontrolcharacters,CRandLF,tostartanewlineofthescreen.TheCRcharactermakesthecursorreturntotheleft-handsideofthescreen.TheLFcharactermakesthecursormoveonelinedown(andmightmakethescreenscroll).

SomeserversonlysendCR,andsothenewlywrittenlineisoverwrittenbythefollowingline.Thisoptioncausesalinefeedsothatalllinesaredisplayed.

4.3.5‘Usebackgroundcolourtoerasescreen’Notallterminalsagreeonwhatcolourtoturnthescreenwhentheserversendsa‘clearscreen’sequence.Someterminalsbelievethescreenshouldalwaysbeclearedtothedefaultbackgroundcolour.Othersbelievethescreenshouldbeclearedtowhatevertheserverhasselectedasabackgroundcolour.

Thereexistapplicationsthatexpectbothkindsofbehaviour.Therefore,PuTTYcanbeconfiguredtodoeither.

Withthisoptiondisabled,screenclearingisalwaysdoneinthedefaultbackgroundcolour.Withthisoptionenabled,itisdoneinthecurrentbackgroundcolour.

Background-colourerasecanbeturnedonandoffbycontrolsequencessentbytheserver.Thisconfigurationoptioncontrolsthedefaultstate,whichwillberestoredwhenyouresettheterminal(seesection3.1.3.6).However,ifyoumodifythisoptioninmid-sessionusing‘ChangeSettings’,itwilltakeeffectimmediately.

4.3.6‘Enableblinkingtext’TheservercanaskPuTTYtodisplaytextthatblinksonandoff.Thisisverydistracting,soPuTTYallowsyoutoturnblinkingtextoffcompletely.

Whenblinkingtextisdisabledandtheserverattemptstomakesometextblink,PuTTYwillinsteaddisplaythetextwithaboldedbackgroundcolour.

Blinkingtextcanbeturnedonandoffbycontrolsequencessentbytheserver.Thisconfigurationoptioncontrolsthedefaultstate,whichwillberestoredwhenyouresettheterminal(seesection3.1.3.6).However,ifyoumodifythisoptioninmid-sessionusing‘ChangeSettings’,itwilltakeeffectimmediately.

4.3.7‘Answerbackto^E’ThisoptioncontrolswhatPuTTYwillsendbacktotheserveriftheserversendsitthe^Eenquirycharacter.Normallyitjustsendsthestring‘PuTTY’.

Ifyouaccidentallywritethecontentsofabinaryfiletoyourterminal,youwillprobablyfindthatitcontainsmorethanone^Echaracter,andasaresultyournextcommandlinewillprobablyread‘PuTTYPuTTYPuTTY...’asifyouhadtypedtheanswerbackstringmultipletimesatthekeyboard.Ifyousettheanswerbackstringtobeempty,thisproblemshouldgoaway,butdoingsomightcauseotherproblems.

NotethatthisisnotthefeatureofPuTTYwhichtheserverwilltypicallyusetodetermineyourterminaltype.Thatfeatureisthe‘Terminal-typestring’intheConnectionpanel;seesection4.14.3fordetails.

Youcanincludecontrolcharactersintheanswerbackstringusing^Cnotation.(Use^~togetaliteral^.)

4.3.8‘Localecho’Withlocalechodisabled,charactersyoutypeintothePuTTYwindowarenotechoedinthewindowbyPuTTY.Theyaresimplysenttotheserver.(Theservermightchoosetoechothembacktoyou;thiscan'tbecontrolledfromthePuTTYcontrolpanel.)

Sometypesofsessionneedlocalecho,andmanydonot.Initsdefaultmode,PuTTYwillautomaticallyattempttodeducewhetherornotlocalechoisappropriateforthesessionyouareworkingin.Ifyoufindithasmadethewrongdecision,youcanusethisconfigurationoptiontooverrideitschoice:youcanforcelocalechotobeturnedon,orforceittobeturnedoff,insteadofrelyingontheautomaticdetection.

4.3.9‘Locallineediting’Normally,everycharacteryoutypeintothePuTTYwindowissentimmediatelytotheserverthemomentyoutypeit.

Ifyouenablelocallineediting,thischanges.PuTTYwillletyoueditawholelineatatimelocally,andthelinewillonlybesenttotheserverwhenyoupressReturn.Ifyoumakeamistake,youcanusetheBackspacekeytocorrectitbeforeyoupressReturn,andtheserverwillneverseethemistake.

Sinceitishardtoeditalinelocallywithoutbeingabletoseeit,locallineeditingismostlyusedinconjunctionwithlocalecho(section4.3.8).ThismakesitidealforuseinrawmodeorwhenconnectingtoMUDsortalkers.(AlthoughsomemoreadvancedMUDsdooccasionallyturnlocallineeditingonandturnlocalechooff,inordertoacceptapasswordfromtheuser.)

Sometypesofsessionneedlocallineediting,andmanydonot.Initsdefaultmode,PuTTYwillautomaticallyattempttodeducewhetherornotlocallineeditingisappropriateforthesessionyouareworkingin.Ifyoufindithasmadethewrongdecision,youcanusethisconfigurationoptiontooverrideitschoice:youcanforcelocallineeditingtobeturnedon,orforceittobeturnedoff,insteadofrelyingontheautomaticdetection.

4.3.10Remote-controlledprintingAlotofVT100-compatibleterminalssupportprintingundercontroloftheremoteserver(sometimescalled‘passthroughprinting’).PuTTYsupportsthisfeatureaswell,butitisturnedoffbydefault.

Toenableremote-controlledprinting,chooseaprinterfromthe‘PrintertosendANSIprinteroutputto’drop-downlistbox.Thisshouldallowyoutoselectfromalltheprintersyouhaveinstalleddriversforonyourcomputer.Alternatively,youcantypethenetworknameofanetworkedprinter(forexample,\\printserver\printer1)evenifyouhaven'talreadyinstalledadriverforitonyourownmachine.

Whentheremoteserverattemptstoprintsomedata,PuTTYwillsendthatdatatotheprinterraw-withouttranslatingit,attemptingtoformatit,ordoinganythingelsetoit.Itisuptoyoutoensureyourremoteserverknowswhattypeofprinteritistalkingto.

SincePuTTYsendsdatatotheprinterraw,itcannotofferoptionssuchasportraitversuslandscape,printquality,orpapertrayselection.AllthesethingswouldbedonebyyourPCprinterdriver(whichPuTTYbypasses);ifyouneedthemdone,youwillhavetofindawaytoconfigureyourremoteservertodothem.

Todisableremoteprintingagain,choose‘None(printingdisabled)’fromtheprinterselectionlist.Thisisthedefaultstate.

4.4TheKeyboardpanelTheKeyboardconfigurationpanelallowsyoutocontrolthebehaviourofthekeyboardinPuTTY.ThecorrectstateformanyofthesesettingsdependsonwhattheservertowhichPuTTYisconnectingexpects.WithaUnixserver,thisislikelytodependonthetermcaporterminfoentryituses,whichinturnislikelytobecontrolledbythe‘Terminal-typestring’settingintheConnectionpanel;seesection4.14.3fordetails.Ifnoneofthesettingshereseemstohelp,youmayfindquestionA.7.13tobeuseful.

4.4.1ChangingtheactionoftheBackspacekey4.4.2ChangingtheactionoftheHomeandEndkeys4.4.3Changingtheactionofthefunctionkeysandkeypad4.4.4ControllingApplicationCursorKeysmode4.4.5ControllingApplicationKeypadmode4.4.6UsingNetHackkeypadmode4.4.7EnablingaDEC-likeComposekey4.4.8‘Control-AltisdifferentfromAltGr’

4.4.1ChangingtheactionoftheBackspacekeySometerminalsbelievethattheBackspacekeyshouldsendthesamethingtotheserverasControl-H(ASCIIcode8).OtherterminalsbelievethattheBackspacekeyshouldsendASCIIcode127(usuallyknownasControl-?)sothatitcanbedistinguishedfromControl-H.ThisoptionallowsyoutochoosewhichcodePuTTYgenerateswhenyoupressBackspace.

IfyouareconnectingoverSSH,PuTTYbydefaulttellstheserverthevalueofthisoption(seesection4.24.2),soyoumayfindthattheBackspacekeydoestherightthingeitherway.Similarly,ifyouareconnectingtoaUnixsystem,youwillprobablyfindthattheUnixsttycommandletsyouconfigurewhichtheserverexpectstosee,soagainyoumightnotneedtochangewhichonePuTTYgenerates.Onothersystems,theserver'sexpectationmightbefixedandyoumighthavenochoicebuttoconfigurePuTTY.

Ifyoudohavethechoice,werecommendconfiguringPuTTYtogenerateControl-?andconfiguringtheservertoexpectit,becausethatallowsapplicationssuchasemacstouseControl-Hforhelp.

(TypingShift-BackspacewillcausePuTTYtosendwhichevercodeisn'tconfiguredhereasthedefault.)

4.4.2ChangingtheactionoftheHomeandEndkeysTheUnixterminalemulatorrxvtdisagreeswiththerestoftheworldaboutwhatcharactersequencesshouldbesenttotheserverbytheHomeandEndkeys.

xterm,andotherterminals,sendESC[1~fortheHomekey,andESC[4~fortheEndkey.rxvtsendsESC[HfortheHomekeyandESC[OwfortheEndkey.

IfyoufindanapplicationonwhichtheHomeandEndkeysaren'tworking,youcouldtryswitchingthisoptiontoseeifithelps.

4.4.3ChangingtheactionofthefunctionkeysandkeypadThisoptionaffectsthefunctionkeys(F1toF12)andthetoprowofthenumerickeypad.

Inthedefaultmode,labelledESC[n~,thefunctionkeysgeneratesequenceslikeESC[11~,ESC[12~andsoon.ThismatchesthegeneralbehaviourofDigital'sterminals.InLinuxmode,F6toF12behavejustlikethedefaultmode,butF1toF5generateESC[[AthroughtoESC[[E.ThismimicstheLinuxvirtualconsole.InXtermR6mode,F5toF12behavelikethedefaultmode,butF1toF4generateESCOPthroughtoESCOS,whicharethesequencesproducedbythetoprowofthekeypadonDigital'sterminals.InVT400mode,allthefunctionkeysbehavelikethedefaultmode,buttheactualtoprowofthenumerickeypadgeneratesESCOPthroughtoESCOS.InVT100+mode,thefunctionkeysgenerateESCOPthroughtoESCO[

InSCOmode,thefunctionkeysF1toF12generateESC[MthroughtoESC[X.Togetherwithshift,theygenerateESC[YthroughtoESC[j.WithcontroltheygenerateESC[kthroughtoESC[v,andwithshiftandcontroltogethertheygenerateESC[wthroughtoESC[{.

Ifyoudon'tknowwhatanyofthismeans,youprobablydon'tneedtofiddlewithit.

4.4.4ControllingApplicationCursorKeysmodeApplicationCursorKeysmodeisawayfortheservertochangethecontrolsequencessentbythearrowkeys.Innormalmode,thearrowkeyssendESC[AthroughtoESC[D.Inapplicationmode,theysendESCOAthroughtoESCOD.

ApplicationCursorKeysmodecanbeturnedonandoffbytheserver,dependingontheapplication.PuTTYallowsyoutoconfiguretheinitialstate.

Youcanalsodisableapplicationcursorkeysmodecompletely,usingthe‘Features’configurationpanel;seesection4.6.1.

4.4.5ControllingApplicationKeypadmodeApplicationKeypadmodeisawayfortheservertochangethebehaviourofthenumerickeypad.

Innormalmode,thekeypadbehaveslikeanormalWindowskeypad:withNumLockon,thenumberkeysgeneratenumbers,andwithNumLockofftheyactlikethearrowkeysandHome,Endetc.

Inapplicationmode,allthekeypadkeyssendspecialcontrolsequences,includingNumLock.NumLockstopsbehavinglikeNumLockandbecomesanotherfunctionkey.

DependingonwhichversionofWindowsyourun,youmayfindtheNumLocklightstillflashesonandoffeverytimeyoupressNumLock,evenwhenapplicationmodeisactiveandNumLockisactinglikeafunctionkey.Thisisunavoidable.

Applicationkeypadmodecanbeturnedonandoffbytheserver,dependingontheapplication.PuTTYallowsyoutoconfiguretheinitialstate.

Youcanalsodisableapplicationkeypadmodecompletely,usingthe‘Features’configurationpanel;seesection4.6.1.

4.4.6UsingNetHackkeypadmodePuTTYhasaspecialmodeforplayingNetHack.Youcanenableitbyselecting‘NetHack’inthe‘Initialstateofnumerickeypad’control.

Inthismode,thenumerickeypadkeys1-9generatetheNetHackmovementcommands(hjklyubn).The5keygeneratesthe.command(donothing).

Inaddition,pressingShiftorCtrlwiththekeypadkeysgeneratetheShift-orCtrl-keysyouwouldexpect(e.g.keypad-7generates‘y’,soShift-keypad-7generates‘Y’andCtrl-keypad-7generatesCtrl-Y);thesecommandstellNetHacktokeepmovingyouinthesamedirectionuntilyouencountersomethinginteresting.

Forsomereason,thisfeatureonlyworksproperlywhenNumLockison.Wedon'tknowwhy.

4.4.7EnablingaDEC-likeComposekeyDECterminalshaveaComposekey,whichprovidesaneasy-to-rememberwayoftypingaccentedcharacters.YoupressComposeandthentypetwomorecharacters.Thetwocharactersare‘combined’toproduceanaccentedcharacter.Thechoicesofcharacteraredesignedtobeeasytoremember;forexample,composing‘e’and‘`’producesthe‘è’character.

IfyourkeyboardhasaWindowsApplicationkey,itactsasaComposekeyinPuTTY.Alternatively,ifyouenablethe‘AltGractsasComposekey’option,theAltGrkeywillbecomeaComposekey.

4.4.8‘Control-AltisdifferentfromAltGr’SomeoldkeyboardsdonothaveanAltGrkey,whichcanmakeitdifficulttotypesomecharacters.PuTTYcanbeconfiguredtotreatthekeycombinationCtrl+LeftAltthesamewayastheAltGrkey.

Bydefault,thischeckboxischecked,andthekeycombinationCtrl+LeftAltdoessomethingcompletelydifferent.PuTTY'susualhandlingoftheleftAltkeyistoprefixtheEscape(Control-[)charactertowhatevercharactersequencetherestofthekeypresswouldgenerate.Forexample,Alt-AgeneratesEscapefollowedbya.SoAlt-Ctrl-AwouldgenerateEscape,followedbyControl-A.

Ifyouuncheckthisbox,Ctrl-AltwillbecomeasynonymforAltGr,soyoucanuseittotypeextragraphiccharactersifyourkeyboardhasany.

(However,Ctrl-AltwillneveractasaComposekey,regardlessofthesettingof‘AltGractsasComposekey’describedinsection4.4.7.)

4.5TheBellpanelTheBellpanelcontrolstheterminalbellfeature:theserver'sabilitytocausePuTTYtobeepatyou.

Inthedefaultconfiguration,whentheserversendsthecharacterwithASCIIcode7(Control-G),PuTTYwillplaytheWindowsDefaultBeepsound.Thisisnotalwayswhatyouwanttheterminalbellfeaturetodo;theBellpanelallowsyoutoconfigurealternativeactions.

4.5.1‘Setthestyleofbell’4.5.2‘Taskbar/captionindicationonbell’4.5.3‘Controlthebelloverloadbehaviour’

4.5.1‘Setthestyleofbell’Thiscontrolallowsyoutoselectvariousdifferentactionstooccuronaterminalbell:

Selecting‘None’disablesthebellcompletely.Inthismode,theservercansendasmanyControl-Gcharactersasitlikesandnothingatallwillhappen.‘Makedefaultsystemalertsound’isthedefaultsetting.ItcausestheWindows‘DefaultBeep’soundtobeplayed.Tochangewhatthissoundis,ortotestitifnothingseemstobehappening,usetheSoundconfigurerintheWindowsControlPanel.‘Visualbell’isasilentalternativetoabeepingcomputer.Inthismode,whentheserversendsaControl-G,thewholePuTTYwindowwillflashwhiteforafractionofasecond.‘BeepusingthePCspeaker’isself-explanatory.‘Playacustomsoundfile’allowsyoutospecifyaparticularsoundfiletobeusedbyPuTTYalone,orevenbyaparticularindividualPuTTYsession.ThisallowsyoutodistinguishyourPuTTYbeepsfromanyotherbeepsonthesystem.Ifyouselectthisoption,youwillalsoneedtoenterthenameofyoursoundfileintheeditcontrol‘Customsoundfiletoplayasabell’.

4.5.2‘Taskbar/captionindicationonbell’ThisfeaturecontrolswhathappenstothePuTTYwindow'sentryintheWindowsTaskbarifabelloccurswhilethewindowdoesnothavetheinputfocus.

Inthedefaultstate(‘Disabled’)nothingunusualhappens.

Ifyouselect‘Steady’,thenwhenabelloccursandthewindowisnotinfocus,thewindow'sTaskbarentryanditstitlebarwillchangecolourtoletyouknowthatPuTTYsessionisaskingforyourattention.Thechangeofcolourwillpersistuntilyouselectthewindow,soyoucanleaveseveralPuTTYwindowsminimisedinyourterminal,goawayfromyourkeyboard,andbesurenottohavemissedanyimportantbeepswhenyougetback.

‘Flashing’isevenmoreeye-catching:theTaskbarentrywillcontinuouslyflashonandoffuntilyouselectthewindow.

4.5.3‘Controlthebelloverloadbehaviour’AcommonusererrorinaterminalsessionistoaccidentallyruntheUnixcommandcat(orequivalent)onaninappropriatefiletype,suchasanexecutable,imagefile,orZIPfile.Thisproducesahugestreamofnon-textcharacterssenttotheterminal,whichtypicallyincludesalotofbellcharacters.Asaresultofthistheterminaloftendoesn'tstopbeepingfortenminutes,andeverybodyelseintheofficegetsannoyed.

Totrytoavoidthisbehaviour,oranyothercauseofexcessivebeeping,PuTTYincludesabelloverloadmanagementfeature.Inthedefaultconfiguration,receivingmorethanfivebellcharactersinatwo-secondperiodwillcausetheoverloadfeaturetoactivate.Oncetheoverloadfeatureisactive,furtherbellswillhavenoeffectatall,sotherestofyourbinaryfilewillbesenttothescreeninsilence.Afteraperiodoffivesecondsduringwhichnofurtherbellsarereceived,theoverloadfeaturewillturnitselfoffagainandbellswillbere-enabled.

Ifyouwantthisfeaturecompletelydisabled,youcanturnitoffusingthecheckbox‘Bellistemporarilydisabledwhenover-used’.

Alternatively,ifyoulikethebelloverloadfeaturebutdon'tagreewiththesettings,youcanconfigurethedetails:howmanybellsconstituteanoverload,howshortatimeperiodtheyhavetoarriveintodoso,andhowmuchsilenttimeisrequiredbeforetheoverloadfeaturewilldeactivateitself.

Belloverloadmodeisalwaysdeactivatedbyanykeypressintheterminal.Thismeansitcanrespondtolargeunexpectedstreamsofdata,butdoesnotinterferewithordinarycommand-lineactivitiesthatgeneratebeeps(suchasfilenamecompletion).

4.6TheFeaturespanelPuTTY'sterminalemulationisveryhighlyfeatured,andcandoalotofthingsunderremoteservercontrol.Someofthesefeaturescancauseproblemsduetobuggyorstrangelyconfiguredserverapplications.

TheFeaturesconfigurationpanelallowsyoutodisablesomeofPuTTY'smoreadvancedterminalfeatures,incasetheycausetrouble.

4.6.1Disablingapplicationkeypadandcursorkeys4.6.2Disablingxterm-stylemousereporting4.6.3Disablingremoteterminalresizing4.6.4Disablingswitchingtothealternatescreen4.6.5Disablingremotewindowtitlechanging4.6.6Responsetoremotewindowtitlequerying4.6.7Disablingremotescrollbackclearing4.6.8Disablingdestructivebackspace4.6.9Disablingremotecharactersetconfiguration4.6.10DisablingArabictextshaping4.6.11Disablingbidirectionaltextdisplay

4.6.1DisablingapplicationkeypadandcursorkeysApplicationkeypadmode(seesection4.4.5)andapplicationcursorkeysmode(seesection4.4.4)alterthebehaviourofthekeypadandcursorkeys.Someapplicationsenablethesemodesbutthendonotdealcorrectlywiththemodifiedkeys.Youcanforcethesemodestobepermanentlydisablednomatterwhattheservertriestodo.

4.6.2Disablingxterm-stylemousereportingPuTTYallowstheservertosendcontrolcodesthatletittakeoverthemouseanduseitforpurposesotherthancopyandpaste.Applicationswhichusethisfeatureincludethetext-modewebbrowserlinks,theUsenetnewsreadertrnversion4,andthefilemanagermc(MidnightCommander).

Ifyoufindthisfeatureinconvenient,youcandisableitusingthe‘Disablexterm-stylemousereporting’control.Withthisboxticked,themousewillalwaysdocopyandpasteinthenormalway.

Notethateveniftheapplicationtakesoverthemouse,youcanstillmanagePuTTY'scopyandpastebyholdingdowntheShiftkeywhileyouselectandpaste,unlessyouhavedeliberatelyturnedthisfeatureoff(seesection4.11.3).

4.6.3DisablingremoteterminalresizingPuTTYhastheabilitytochangetheterminal'ssizeandpositioninresponsetocommandsfromtheserver.IfyoufindPuTTYisdoingthisunexpectedlyorinconveniently,youcantellPuTTYnottorespondtothoseservercommands.

4.6.4DisablingswitchingtothealternatescreenManyterminals,includingPuTTY,supportan‘alternatescreen’.Thisisthesamesizeastheordinaryterminalscreen,butseparate.Typicallyascreen-basedprogramsuchasatexteditormightswitchtheterminaltothealternatescreenbeforestartingup.Thenattheendoftherun,itswitchesbacktotheprimaryscreen,andyouseethescreencontentsjustastheywerebeforestartingtheeditor.

Somepeoplepreferthisnottohappen.Ifyouwantyoureditortoruninthesamescreenastherestofyourterminalactivity,youcandisablethealternatescreenfeaturecompletely.

4.6.5DisablingremotewindowtitlechangingPuTTYhastheabilitytochangethewindowtitleinresponsetocommandsfromtheserver.IfyoufindPuTTYisdoingthisunexpectedlyorinconveniently,youcantellPuTTYnottorespondtothoseservercommands.

4.6.6ResponsetoremotewindowtitlequeryingPuTTYcanoptionallyprovidethextermserviceofallowingserverapplicationstofindoutthelocalwindowtitle.Thisfeatureisdisabledbydefault,butyoucanturnitonifyoureallywantit.

NOTEthatthisfeatureisapotentialsecurityhazard.Ifamaliciousapplicationcanwritedatatoyourterminal(forexample,ifyoumerelycatafileownedbysomeoneelseontheservermachine),itcanchangeyourwindowtitle(unlessyouhavedisabledthisasmentionedinsection4.6.5)andthenusethisservicetohavethenewwindowtitlesentbacktotheserverasiftypedatthekeyboard.Thisallowsanattackertofakekeypressesandpotentiallycauseyourserver-sideapplicationstodothingsyoudidn'twant.Thereforethisfeatureisdisabledbydefault,andwerecommendyoudonotsetitto‘Windowtitle’unlessyoureallyknowwhatyouaredoing.

Therearethreesettingsforthisoption:

‘None’PuTTYmakesnoresponsewhatsoevertotherelevantescapesequence.Thismayupsetserver-sidesoftwarethatisexpectingsomesortofresponse.

‘Emptystring’PuTTYmakesawell-formedresponse,butleavesitblank.Thus,server-sidesoftwarethatexpectsaresponseiskepthappy,butanattackercannotinfluencetheresponsestring.Thisisprobablythesettingyouwantifyouhavenobetterideas.

‘Windowtitle’PuTTYrespondswiththeactualwindowtitle.Thisisdangerousforthereasonsdescribedabove.

4.6.7DisablingremotescrollbackclearingPuTTYhastheabilitytocleartheterminal'sscrollbackbufferinresponsetoacommandfromtheserver.IfyoufindPuTTYisdoingthisunexpectedlyorinconveniently,youcantellPuTTYnottorespondtothatservercommand.

4.6.8DisablingdestructivebackspaceNormally,whenPuTTYreceivescharacter127(^?)fromtheserver,itwillperforma‘destructivebackspace’:movethecursoronespaceleftanddeletethecharacterunderit.Thiscanapparentlycauseproblemsinsomeapplications,soPuTTYprovidestheabilitytoconfigurecharacter127toperformanormalbackspace(withoutdeletingacharacter)instead.

4.6.9DisablingremotecharactersetconfigurationPuTTYhastheabilitytochangeitscharactersetconfigurationinresponsetocommandsfromtheserver.Someprogramssendthesecommandsunexpectedlyorinconveniently.Inparticular,BitchX(anIRCclient)seemstohaveahabitofreconfiguringthecharactersettosomethingotherthantheuserintended.

Ifyoufindthataccentedcharactersarenotshowingupthewayyouexpectthemto,particularlyifyou'rerunningBitchX,youcouldtrydisablingtheremotecharactersetconfigurationcommands.

4.6.10DisablingArabictextshapingPuTTYsupportsshapingofArabictext,whichmeansthatifyourserversendstextwritteninthebasicUnicodeArabicalphabetthenitwillconvertittothecorrectdisplayformsbeforeprintingitonthescreen.

Ifyouareusingfull-screensoftwarewhichwasnotexpectingthistohappen(especiallyifyouarenotanArabicspeakerandyouunexpectedlyfindyourselfdealingwithArabictextfilesinapplicationswhicharenotArabic-aware),youmightfindthatthedisplaybecomescorrupted.Bytickingthisbox,youcandisableArabictextshapingsothatPuTTYdisplayspreciselythecharactersitistoldtodisplay.

Youmayalsofindyouneedtodisablebidirectionaltextdisplay;seesection4.6.11.

4.6.11DisablingbidirectionaltextdisplayPuTTYsupportsbidirectionaltextdisplay,whichmeansthatifyourserversendstextwritteninalanguagewhichisusuallydisplayedfromrighttoleft(suchasArabicorHebrew)thenPuTTYwillautomaticallyflipitroundsothatitisdisplayedintherightdirectiononthescreen.

Ifyouareusingfull-screensoftwarewhichwasnotexpectingthistohappen(especiallyifyouarenotanArabicspeakerandyouunexpectedlyfindyourselfdealingwithArabictextfilesinapplicationswhicharenotArabic-aware),youmightfindthatthedisplaybecomescorrupted.Bytickingthisbox,youcandisablebidirectionaltextdisplay,sothatPuTTYdisplaystextfromlefttorightinallsituations.

YoumayalsofindyouneedtodisableArabictextshaping;seesection4.6.10.

4.7TheWindowpanelTheWindowconfigurationpanelallowsyoutocontrolaspectsofthePuTTYwindow.

4.7.1SettingthesizeofthePuTTYwindow4.7.2Whattodowhenthewindowisresized4.7.3Controllingscrollback4.7.4‘Pusherasedtextintoscrollback’

4.7.1SettingthesizeofthePuTTYwindowThe‘Columns’and‘Rows’boxesletyousetthePuTTYwindowtoaprecisesize.Ofcourseyoucanalsodragthewindowtoanewsizewhileasessionisrunning.

4.7.2WhattodowhenthewindowisresizedTheseoptionsallowyoutocontrolwhathappenswhentheusertriestoresizethePuTTYwindowusingitswindowfurniture.

Therearefouroptionshere:

‘Changethenumberofrowsandcolumns’:thefontsizewillnotchange.(Thisisthedefault.)‘Changethesizeofthefont’:thenumberofrowsandcolumnsintheterminalwillstaythesame,andthefontsizewillchange.‘Changefontsizewhenmaximised’:whenthewindowisresized,thenumberofrowsandcolumnswillchange,exceptwhenthewindowismaximised(orrestored),whenthefontsizewillchange.(Inthismode,holdingdowntheAltkeywhileresizingwillalsocausethefontsizetochange.)‘Forbidresizingcompletely’:theterminalwillrefusetoberesizedatall.

4.7.3ControllingscrollbackTheseoptionsletyouconfigurethewayPuTTYkeepstextafteritscrollsoffthetopofthescreen(seesection3.1.2).

The‘Linesofscrollback’boxletsyouconfigurehowmanylinesoftextPuTTYkeeps.The‘Displayscrollbar’optionsallowyoutohidethescrollbar(althoughyoucanstillviewthescrollbackusingthekeyboardasdescribedinsection3.1.2).Youcanseparatelyconfigurewhetherthescrollbarisshowninfull-screenmodeandinnormalmodes.

IfyouareviewingpartofthescrollbackwhentheserversendsmoretexttoPuTTY,thescreenwillreverttoshowingthecurrentterminalcontents.Youcandisablethisbehaviourbyturningoff‘Resetscrollbackondisplayactivity’.Youcanalsomakethescreenrevertwhenyoupressakey,byturningon‘Resetscrollbackonkeypress’.

4.7.4‘Pusherasedtextintoscrollback’Whenthisoptionisenabled,thecontentsoftheterminalscreenwillbepushedintothescrollbackwhenaserver-sideapplicationclearsthescreen,sothatyourscrollbackwillcontainabetterrecordofwhatwasonyourscreeninthepast.

Iftheapplicationswitchestothealternatescreen(seesection4.6.4formoreaboutthis),thenthecontentsoftheprimaryscreenwillbevisibleinthescrollbackuntiltheapplicationswitchesbackagain.

Thisoptionisenabledbydefault.

4.8TheAppearancepanelTheAppearanceconfigurationpanelallowsyoutocontrolaspectsoftheappearanceofPuTTY'swindow.

4.8.1Controllingtheappearanceofthecursor4.8.2Controllingthefontusedintheterminalwindow4.8.3‘Hidemousepointerwhentypinginwindow’4.8.4Controllingthewindowborder

4.8.1ControllingtheappearanceofthecursorThe‘Cursorappearance’optionletsyouconfigurethecursortobeablock,anunderline,oraverticalline.Ablockcursorbecomesanemptyboxwhenthewindowlosesfocus;anunderlineoraverticallinebecomesdotted.

The‘Cursorblinks’optionmakesthecursorblinkonandoff.Thisworksinanyofthecursormodes.

4.8.2ControllingthefontusedintheterminalwindowThisoptionallowsyoutochoosewhatfont,inwhatsize,thePuTTYterminalwindowusestodisplaythetextinthesession.

Bydefault,youwillbeofferedachoicefromallthefixed-widthfontsinstalledonthesystem,sinceVT100-styleterminalhandlingexpectsafixed-widthfont.Ifyouticktheboxmarked‘Allowselectionofvariable-pitchfonts’,however,PuTTYwilloffervariable-widthfontsaswell:ifyouselectoneofthese,thefontwillbecoercedintofixed-sizecharactercells,whichwillprobablynotlookverygood(butcanworkOKwithsomefonts).

4.8.3‘Hidemousepointerwhentypinginwindow’Ifyouenablethisoption,themousepointerwilldisappearifthePuTTYwindowisselectedandyoupressakey.Thisway,itwillnotobscureanyofthetextinthewindowwhileyouworkinyoursession.Assoonasyoumovethemouse,thepointerwillreappear.

Thisoptionisdisabledbydefault,sothemousepointerremainsvisibleatalltimes.

4.8.4ControllingthewindowborderPuTTYallowsyoutoconfiguretheappearanceofthewindowbordertosomeextent.

Thecheckboxmarked‘Sunken-edgeborder’changestheappearanceofthewindowbordertosomethingmorelikeaDOSbox:theinsideedgeoftheborderishighlightedasifitsankdowntomeetthesurfaceinsidethewindow.Thismakestheborderalittlebitthickeraswell.It'shardtodescribewell.Tryitandseeifyoulikeit.

Youcanalsoconfigureacompletelyblankgapbetweenthetextinthewindowandtheborder,usingthe‘Gapbetweentextandwindowedge’control.Bydefaultthisissetatonepixel.Youcanreduceittozero,orincreaseitfurther.

4.9TheBehaviourpanelTheBehaviourconfigurationpanelallowsyoutocontrolaspectsofthebehaviourofPuTTY'swindow.

4.9.1Controllingthewindowtitle4.9.2‘Warnbeforeclosingwindow’4.9.3‘WindowclosesonALT-F4’4.9.4‘SystemmenuappearsonALT-Space’4.9.5‘SystemmenuappearsonAltalone’4.9.6‘Ensurewindowisalwaysontop’4.9.7‘FullscreenonAlt-Enter’

4.9.1ControllingthewindowtitleThe‘Windowtitle’editboxallowsyoutosetthetitleofthePuTTYwindow.Bydefaultthewindowtitlewillcontainthehostnamefollowedby‘PuTTY’,forexampleserver1.example.com-PuTTY.Ifyouwantadifferentwindowtitle,thisiswheretosetit.

PuTTYallowstheservertosendxtermcontrolsequenceswhichmodifythetitleofthewindowinmid-session(unlessthisisdisabled-seesection4.6.5);thetitlestringsethereisthereforeonlytheinitialwindowtitle.

Aswellasthewindowtitle,thereisalsoanxtermsequencetomodifythetitleofthewindow'sicon.Thismakessenseinawindowingsystemwherethewindowbecomesaniconwhenminimised,suchasWindows3.1ormostXWindowSystemsetups;butintheWindows95-likeuserinterfaceitisn'tasapplicable.

Bydefault,PuTTYonlyusestheserver-suppliedwindowtitle,andignorestheicontitleentirely.Ifforsomereasonyouwanttoseebothtitles,checktheboxmarked‘Separatewindowandicontitles’.Ifyoudothis,PuTTY'swindowtitleandTaskbarcaptionwillchangeintotheserver-suppliedicontitleifyouminimisethePuTTYwindow,andchangebacktotheserver-suppliedwindowtitleifyourestoreit.(Iftheserverhasnotbotheredtosupplyawindoworicontitle,noneofthiswillhappen.)

4.9.2‘Warnbeforeclosingwindow’IfyoupresstheClosebuttoninaPuTTYwindowthatcontainsarunningsession,PuTTYwillputupawarningwindowaskingifyoureallymeanttoclosethewindow.Awindowwhosesessionhasalreadyterminatedcanalwaysbeclosedwithoutawarning.

Ifyouwanttobeabletocloseawindowquickly,youcandisablethe‘Warnbeforeclosingwindow’option.

4.9.3‘WindowclosesonALT-F4’Bydefault,pressingALT-F4causesthewindowtoclose(orawarningboxtoappear;seesection4.9.2).Ifyoudisablethe‘WindowclosesonALT-F4’option,thenpressingALT-F4willsimplysendakeysequencetotheserver.

4.9.4‘SystemmenuappearsonALT-Space’Ifthisoptionisenabled,thenpressingALT-SpacewillbringupthePuTTYwindow'smenu,likeclickingonthetopleftcorner.Ifitisdisabled,thenpressingALT-SpacewilljustsendESCSPACEtotheserver.

SomeaccessibilityprogramsforWindowsmayneedthisoptionenablingtobeabletocontrolPuTTY'swindowsuccessfully.Forinstance,DragonNaturallySpeakingrequiresitbothtoopenthesystemmenuviavoice,andtoclose,minimise,maximiseandrestorethewindow.

4.9.5‘SystemmenuappearsonAltalone’Ifthisoptionisenabled,thenpressingandreleasingALTwillbringupthePuTTYwindow'smenu,likeclickingonthetopleftcorner.Ifitisdisabled,thenpressingandreleasingALTwillhavenoeffect.

4.9.6‘Ensurewindowisalwaysontop’Ifthisoptionisenabled,thePuTTYwindowwillstayontopofallotherwindows.

4.9.7‘FullscreenonAlt-Enter’Ifthisoptionisenabled,thenpressingAlt-EnterwillcausethePuTTYwindowtobecomefull-screen.PressingAlt-Enteragainwillrestorethepreviouswindowsize.

Thefull-screenfeatureisalsoavailablefromtheSystemmenu,evenwhenitisconfigurednottobeavailableontheAlt-Enterkey.Seesection3.1.3.7.

4.10TheTranslationpanelTheTranslationconfigurationpanelallowsyoutocontrolthetranslationbetweenthecharactersetunderstoodbytheserverandthecharactersetunderstoodbyPuTTY.

4.10.1Controllingcharactersettranslation4.10.2‘TreatCJKambiguouscharactersaswide’4.10.3‘CapsLockactsasCyrillicswitch’4.10.4Controllingdisplayofline-drawingcharacters4.10.5Controllingcopyandpasteoflinedrawingcharacters

4.10.1ControllingcharactersettranslationDuringaninteractivesession,PuTTYreceivesastreamof8-bitbytesfromtheserver,andinordertodisplaythemonthescreenitneedstoknowwhatcharactersettointerpretthemin.Similarly,PuTTYneedstoknowhowtotranslateyourkeystrokesintotheencodingtheserverexpects.Unfortunately,thereisnosatisfactorymechanismforPuTTYandtheservertocommunicatethisinformation,soitmustusuallybemanuallyconfigured.

Therearealotofcharactersetstochoosefrom.The‘Remotecharacterset’optionletsyouselectone.

BydefaultPuTTYwillusetheUTF-8encodingofUnicode,whichcanrepresentprettymuchanycharacter;datacomingfromtheserverisinterpretedasUTF-8,andkeystrokesaresentUTF-8encoded.ThisiswhatmostmoderndistributionsofLinuxwillexpectbydefault.However,ifthisiswrongforyourserver,youcanselectadifferentcharactersetusingthiscontrol.

Afewothernotablecharactersetsare:

TheISO-8859seriesareallstandardcharactersetsthatincludevariousaccentedcharactersappropriatefordifferentsetsoflanguages.TheWin125xseriesaredefinedbyMicrosoft,forsimilarpurposes.InparticularWin1252isalmostequivalenttoISO-8859-1,butcontainsafewextracharacterssuchasmatchedquotesandtheEurosymbol.IfyouwanttheoldIBMPCcharactersetwithblockgraphicsandline-drawingcharacters,youcanselect‘CP437’.

Ifyouneedsupportforanumericcodepagewhichisnotlistedinthedrop-downlist,suchascodepage866,thenyoucantryenteringitsnamemanually(CP866forexample)inthelistbox.IftheunderlyingversionofWindowshastheappropriatetranslationtableinstalled,PuTTYwilluseit.

4.10.2‘TreatCJKambiguouscharactersaswide’TherearesomeUnicodecharacterswhosewidthisnotwell-defined.Inmostcontexts,suchcharactersshouldbetreatedassingle-widthforthepurposesofwrappingandsoon;however,insomeCJKcontexts,theyarebettertreatedasdouble-widthforhistoricalreasons,andsomeserver-sideapplicationsmayexpectthemtobedisplayedassuch.SettingthisoptionwillcausePuTTYtotakethedouble-widthinterpretation.

IfyouuselegacyCJKapplications,andyoufindyourlinesarewrappinginthewrongplaces,oryouarehavingotherdisplayproblems,youmightwanttoplaywiththissetting.

ThisoptiononlyhasanyeffectinUTF-8mode(seesection4.10.1).

4.10.3‘CapsLockactsasCyrillicswitch’ThisfeatureallowsyoutoswitchbetweenaUS/UKkeyboardlayoutandaCyrillickeyboardlayoutbyusingtheCapsLockkey,ifyouneedtotype(forexample)RussianandEnglishsidebysideinthesamedocument.

CurrentlythisfeatureisnotexpectedtoworkproperlyifyournativekeyboardlayoutisnotUSorUK.

4.10.4Controllingdisplayofline-drawingcharactersVT100-seriesterminalsallowtheservertosendcontrolsequencesthatshifttemporarilyintoaseparatecharactersetfordrawingsimplelinesandboxes.However,thereareavarietyofwaysinwhichPuTTYcanattempttofindappropriatecharacters,andtherightonetousedependsonthelocallyconfiguredfont.Ingeneralyoushouldprobablytrylotsofoptionsuntilyoufindonethatyourparticularfontsupports.

‘UseUnicodelinedrawingcodepoints’triestousetheboxcharactersthatarepresentinUnicode.ForgoodUnicode-supportingfontsthisisprobablythemostreliableandfunctionaloption.‘Poorman'slinedrawing’assumesthatthefontcannotgeneratethelineandboxcharactersatall,soitwillusethe+,-and|characterstodrawapproximationstoboxes.Youshouldusethisoptionifnoneoftheotheroptionsworks.‘FonthasXWindowsencoding’isforusewithfontsthathaveaspecialencoding,wherethelowest32characterpositions(belowtheASCIIprintablerange)containtheline-drawingcharacters.ThisisunlikelytobethecasewithanystandardWindowsfont;itwillprobablyonlyapplytocustom-builtfontsorfontsthathavebeenautomaticallyconvertedfromtheXWindowSystem.‘UsefontinbothANSIandOEMmodes’triestousethesamefontintwodifferentcharactersets,toobtainawiderrangeofcharacters.Thisdoesn'talwayswork;somefontsclaimtobeadifferentsizedependingonwhichcharactersetyoutrytouse.‘UsefontinOEMmodeonly’ismorereliablethanthat,butcanmissoutothercharactersfromthemaincharacterset.

4.10.5ControllingcopyandpasteoflinedrawingcharactersBydefault,whenyoucopyandpasteapieceofthePuTTYscreenthatcontainsVT100lineandboxdrawingcharacters,PuTTYwillpastethemintheformtheyappearonthescreen:eitherUnicodelinedrawingcodepoints,orthe‘poorman's’line-drawingcharacters+,-and|.Thecheckbox‘CopyandpasteVT100linedrawingcharsaslqqqk’disablesthisfeature,soline-drawingcharacterswillbepastedastheASCIIcharactersthatwereprintedtoproducethem.Thiswilltypicallymeantheycomeoutmostlyasqandx,withascatteringofjklmntuvwatthecorners.Thismightbeusefulifyouweretryingtorecreatethesameboxlayoutinanotherprogram,forexample.

Notethatthisoptiononlyappliestoline-drawingcharacterswhichwereprintedbyusingtheVT100mechanism.Line-drawingcharactersthatwerereceivedasUnicodecodepointswillpasteasUnicodealways.

4.11TheSelectionpanelTheSelectionpanelallowsyoutocontrolthewaycopyandpasteworkinthePuTTYwindow.

4.11.1PastinginRichTextFormat4.11.2Changingtheactionsofthemousebuttons4.11.3‘Shiftoverridesapplication'suseofmouse’4.11.4Defaultselectionmode4.11.5Configuringword-by-wordselection

4.11.1PastinginRichTextFormatIfyouenable‘PastetoclipboardinRTFaswellasplaintext’,PuTTYwillwriteformattinginformationtotheclipboardaswellastheactualtextyoucopy.Theeffectofthisisthatifyoupasteinto(say)awordprocessor,thetextwillappearinthewordprocessorinthesamefont,colour,andstyle(e.g.bold,underline)PuTTYwasusingtodisplayit.

Thisoptioncaneasilybeinconvenient,sobydefaultitisdisabled.

4.11.2ChangingtheactionsofthemousebuttonsPuTTY'scopyandpastemechanismisbydefaultmodelledontheUnixxtermapplication.TheXWindowSystemusesathree-buttonmouse,andtheconventionisthattheleftbuttonselects,therightbuttonextendsanexistingselection,andthemiddlebuttonpastes.

Windowsoftenonlyhastwomousebuttons,soinPuTTY'sdefaultconfiguration(‘Compromise’),therightbuttonpastes,andthemiddlebutton(ifyouhaveone)extendsaselection.

Ifyouhaveathree-buttonmouseandyouarealreadyusedtothextermarrangement,youcanselectitusingthe‘Actionofmousebuttons’control.

Alternatively,withthe‘Windows’optionselected,themiddlebuttonextends,andtherightbuttonbringsupacontextmenu(onwhichoneoftheoptionsis‘Paste’).(ThiscontextmenuisalwaysavailablebyholdingdownCtrlandright-clicking,regardlessofthesettingofthisoption.)

4.11.3‘Shiftoverridesapplication'suseofmouse’PuTTYallowstheservertosendcontrolcodesthatletittakeoverthemouseanduseitforpurposesotherthancopyandpaste.Applicationswhichusethisfeatureincludethetext-modewebbrowserlinks,theUsenetnewsreadertrnversion4,andthefilemanagermc(MidnightCommander).

Whenrunningoneoftheseapplications,pressingthemousebuttonsnolongerperformscopyandpaste.Ifyoudoneedtocopyandpaste,youcanstilldosoifyouholddownShiftwhileyoudoyourmouseclicks.

However,itispossibleintheoryforapplicationstoevendetectandmakeuseofShift+mouseclicks.Wedon'tknowofanyapplicationsthatdothis,butincasesomeoneeverwritesone,uncheckingthe‘Shiftoverridesapplication'suseofmouse’checkboxwillcauseShift+mouseclickstogototheserveraswell(sothatmouse-drivencopyandpastewillbecompletelydisabled).

Ifyouwanttopreventtheapplicationfromtakingoverthemouseatall,youcandothisusingtheFeaturescontrolpanel;seesection4.6.2.

4.11.4DefaultselectionmodeAsdescribedinsection3.1.1,PuTTYhastwomodesofselectingtexttobecopiedtotheclipboard.Inthedefaultmode(‘Normal’),draggingthemousefrompointAtopointBselectstotheendofthelinecontainingA,allthelinesinbetween,andfromtheverybeginningofthelinecontainingB.Intheothermode(‘Rectangularblock’),draggingthemousebetweentwopointsdefinesarectangle,andeverythingwithinthatrectangleiscopied.

Normally,youhavetoholddownAltwhiledraggingthemousetoselectarectangularblock.Usingthe‘Defaultselectionmode’control,youcansetrectangularselectionasthedefault,andthenyouhavetoholddownAlttogetthenormalbehaviour.

4.11.5Configuringword-by-wordselectionPuTTYwillselectawordatatimeintheterminalwindowifyoudouble-clicktobeginthedrag.Thispanelallowsyoutocontrolpreciselywhatisconsideredtobeaword.

Eachcharacterisgivenaclass,whichisasmallnumber(typically0,1or2).PuTTYconsidersasinglewordtobeanynumberofadjacentcharactersinthesameclass.Sobymodifyingtheassignmentofcharacterstoclasses,youcanmodifytheword-by-wordselectionbehaviour.

Inthedefaultconfiguration,thecharacterclassesare:

Class0containswhitespaceandcontrolcharacters.Class1containsmostpunctuation.Class2containsletters,numbersandafewpiecesofpunctuation(thedoublequote,minussign,period,forwardslashandunderscore).

So,forexample,ifyouassignthe@symbolintocharacterclass2,youwillbeabletoselectane-mailaddresswithjustadoubleclick.

Inordertoadjusttheseassignments,youstartbyselectingagroupofcharactersinthelistbox.Thenenteraclassnumberintheeditboxbelow,andpressthe‘Set’button.

ThismechanismcurrentlyonlycoversASCIIcharacters,becauseitisn'tfeasibletoexpandthelisttocoverthewholeofUnicode.

Characterclassdefinitionscanbemodifiedbycontrolsequencessentbytheserver.Thisconfigurationoptioncontrolsthedefaultstate,whichwillberestoredwhenyouresettheterminal(seesection3.1.3.6).However,ifyoumodifythisoptioninmid-sessionusing‘ChangeSettings’,itwilltakeeffectimmediately.

4.12TheColourspanelTheColourspanelallowsyoutocontrolPuTTY'suseofcolour.

4.12.1‘AllowterminaltospecifyANSIcolours’4.12.2‘Allowterminaltousexterm256-colourmode’4.12.3‘Indicateboldedtextbychanging...’4.12.4‘Attempttouselogicalpalettes’4.12.5‘Usesystemcolours’4.12.6Adjustingthecoloursintheterminalwindow

4.12.1‘AllowterminaltospecifyANSIcolours’Thisoptionisenabledbydefault.Ifitisdisabled,PuTTYwillignoreanycontrolsequencessentbytheservertorequestcolouredtext.

Ifyouhaveaparticularlygarishapplication,youmightwanttoturnthisoptionoffandmakePuTTYonlyusethedefaultforegroundandbackgroundcolours.

4.12.2‘Allowterminaltousexterm256-colourmode’Thisoptionisenabledbydefault.Ifitisdisabled,PuTTYwillignoreanycontrolsequencessentbytheserverwhichusetheextended256-colourmodesupportedbyrecentversionsofxterm.

Ifyouhaveanapplicationwhichissupposedtouse256-colourmodeanditisn'tworking,youmayfindyouneedtotellyourserverthatyourterminalsupports256colours.OnUnix,youdothisbyensuringthatthesettingofTERMdescribesa256-colour-capableterminal.Youcancheckthisusingacommandsuchasinfocmp:

$infocmp|grepcolors

colors#256,cols#80,it#8,lines#24,pairs#256,

Ifyoudonotsee‘colors#256’intheoutput,youmayneedtochangeyourterminalsetting.OnmodernLinuxmachines,youcouldtry‘xterm-256color’.

4.12.3‘Indicateboldedtextbychanging...’Whentheserversendsacontrolsequenceindicatingthatsometextshouldbedisplayedinbold,PuTTYcanhandlethisinseveralways.Itcaneitherchangethefontforaboldversion,orusethesamefontinabrightercolour,oritcandoboth(brightenthecolourandemboldenthefont).Thiscontrolletsyouchoosewhich.

Bydefaultboldisindicatedbycolour,sonon-boldtextisdisplayedinlightgreyandboldtextisdisplayedinbrightwhite(andsimilarlyinothercolours).Ifyouchangethesettingto‘Thefont’box,boldandnon-boldtextwillbedisplayedinthesamecolour,andinsteadthefontwillchangetoindicatethedifference.Ifyouselect‘Both’,thefontandthecolourwillbothchange.

Someapplicationsrelyon‘boldblack’beingdistinguishablefromablackbackground;ifyouchoose‘Thefont’,theirtextmaybecomeinvisible.

4.12.4‘Attempttouselogicalpalettes’LogicalpalettesareamechanismbywhichaWindowsapplicationrunningonan8-bitcolourdisplaycanselectpreciselythecoloursitwantsinsteadofgoingwiththeWindowsstandarddefaults.

Ifyouarenotgettingthecoloursyouaskforonan8-bitdisplay,youcantryenablingthisoption.However,bewarnedthatit'sneverworkedverywell.

4.12.5‘Usesystemcolours’EnablingthisoptionwillcausePuTTYtoignoretheconfiguredcoloursfor‘DefaultBackground/Foreground’and‘CursorColour/Text’(seesection4.12.6),insteadgoingwiththesystem-widedefaults.

Notethatnon-boldandboldtextwillbethesamecolourifthisoptionisenabled.Youmightwanttochangetoindicatingboldtextbyfontchanges(seesection4.12.3).

4.12.6AdjustingthecoloursintheterminalwindowThemaincolourcontrolallowsyoutospecifyexactlywhatcoloursthingsshouldbedisplayedin.TomodifyoneofthePuTTYcolours,usethelistboxtoselectwhichcolouryouwanttomodify.TheRGBvaluesforthatcolourwillappearontheright-handsideofthelistbox.Now,ifyoupressthe‘Modify’button,youwillbepresentedwithacolourselector,inwhichyoucanchooseanewcolourtogoinplaceoftheoldone.(YoumayalsoedittheRGBvaluesdirectlyintheeditboxes,ifyouwish;eachvalueisanintegerfrom0to255.)

PuTTYallowsyoutosetthecursorcolour,thedefaultforegroundandbackground,andthepreciseshadesofalltheANSIconfigurablecolours(black,red,green,yellow,blue,magenta,cyan,andwhite).Youcanalsomodifythepreciseshadesusedfortheboldversionsofthesecolours;theseareusedtodisplayboldtextifyouhavechosentoindicatethatbycolour(seesection4.12.3),andcanalsobeusediftheserverasksspecificallytousethem.(Notethat‘DefaultBoldBackground’isnotthebackgroundcolourusedforboldtext;itisonlyusediftheserverspecificallyasksforaboldbackground.)

4.13TheConnectionpanelTheConnectionpanelallowsyoutoconfigureoptionsthatapplytomorethanonetypeofconnection.

4.13.1Usingkeepalivestopreventdisconnection4.13.2‘DisableNagle'salgorithm’4.13.3‘EnableTCPkeepalives’4.13.4‘Internetprotocol’4.13.5‘Logicalnameofremotehost’

4.13.1UsingkeepalivestopreventdisconnectionIfyoufindyoursessionsareclosingunexpectedly(mostoftenwith‘Connectionresetbypeer’)aftertheyhavebeenidleforawhile,youmightwanttotryusingthisoption.

Somenetworkroutersandfirewallsneedtokeeptrackofallconnectionsthroughthem.Usually,thesefirewallswillassumeaconnectionisdeadifnodataistransferredineitherdirectionafteracertaintimeinterval.ThiscancausePuTTYsessionstobeunexpectedlyclosedbythefirewallifnotrafficisseeninthesessionforsometime.

Thekeepaliveoption(‘Secondsbetweenkeepalives’)allowsyoutoconfigurePuTTYtosenddatathroughthesessionatregularintervals,inawaythatdoesnotdisrupttheactualterminalsession.Ifyoufindyourfirewalliscuttingidleconnectionsoff,youcantryenteringanon-zerovalueinthisfield.Thevalueismeasuredinseconds;so,forexample,ifyourfirewallcutsconnectionsoffaftertenminutesthenyoumightwanttoenter300seconds(5minutes)inthebox.

Notethatkeepalivesarenotalwayshelpful.Theyhelpifyouhaveafirewallwhichdropsyourconnectionafteranidleperiod;butifthenetworkbetweenyouandtheserversuffersfrombreaksinconnectivitythenkeepalivescanactuallymakethingsworse.Ifasessionisidle,andconnectivityistemporarilylostbetweentheendpoints,buttheconnectivityisrestoredbeforeeithersidetriestosendanything,thentherewillbenoproblem-neitherendpointwillnoticethatanythingwaswrong.However,ifonesidedoessendsomethingduringthebreak,itwillrepeatedlytrytore-send,andeventuallygiveupandabandontheconnection.Thenwhenconnectivityisrestored,theothersidewillfindthatthefirstsidedoesn'tbelievethereisanopenconnectionanymore.Keepalivescanmakethissortofproblemworse,becausetheyincreasetheprobabilitythatPuTTYwillattempttosenddataduringabreakinconnectivity.(Othertypesofperiodicnetworkactivitycancausethisbehaviour;inparticular,SSH-2re-keyscanhavethiseffect.Seesection4.19.2.)

Therefore,youmightfindthatkeepaliveshelpconnectionloss,oryoumightfindtheymakeitworse,dependingonwhatkindofnetworkproblemsyouhavebetweenyouandtheserver.

KeepalivesareonlysupportedinTelnetandSSH;theRloginandRawprotocolsoffernowayofimplementingthem.(Foranalternative,seesection4.13.3.)

NotethatifyouareusingSSH-1andtheserverhasabugthatmakesitunabletodealwithSSH-1ignoremessages(seesection4.27.1),enablingkeepaliveswillhavenoeffect.

4.13.2‘DisableNagle'salgorithm’Nagle'salgorithmisadetailofTCP/IPimplementationsthattriestominimisethenumberofsmalldatapacketssentdownanetworkconnection.WithNagle'salgorithmenabled,PuTTY'sbandwidthusagewillbeslightlymoreefficient;withitdisabled,youmayfindyougetafasterresponsetoyourkeystrokeswhenconnectingtosometypesofserver.

TheNaglealgorithmisdisabledbydefaultforinteractiveconnections.

4.13.3‘EnableTCPkeepalives’NOTE:TCPkeepalivesshouldnotbeconfusedwiththeapplication-levelkeepalivesdescribedinsection4.13.1.Ifindoubt,youprobablywantapplication-levelkeepalives;TCPkeepalivesareprovidedforcompleteness.

TheideaofTCPkeepalivesissimilartoapplication-levelkeepalives,andthesamecaveatsapply.Themaindifferencesare:

TCPkeepalivesareavailableonallconnectiontypes,includingRawandRlogin.TheintervalbetweenTCPkeepalivesisusuallymuchlonger,typicallytwohours;thisissetbytheoperatingsystem,andcannotbeconfiguredwithinPuTTY.Iftheoperatingsystemdoesnotreceivearesponsetoakeepalive,itmaysendoutmoreinquicksuccessionandterminatetheconnectionifnoresponseisreceived.

TCPkeepalivesmaybemoreusefulforensuringthathalf-openconnectionsareterminatedthanforkeepingaconnectionalive.

TCPkeepalivesaredisabledbydefault.

4.13.4‘Internetprotocol’ThisoptionallowstheusertoselectbetweentheoldandnewInternetprotocolsandaddressingschemes(IPv4andIPv6).Theselectedprotocolwillbeusedformostoutgoingnetworkconnections(includingconnectionstoproxies);however,tunnelshavetheirownconfiguration,forwhichseesection4.26.2.

Thedefaultsettingis‘Auto’,whichmeansPuTTYwilldosomethingsensibleandtrytoguesswhichprotocolyouwanted.(IfyouspecifyaliteralInternetaddress,itwillusewhicheverprotocolthataddressimplies.Ifyouprovideahostname,itwillseewhatkindsofaddressexistforthathostname;itwilluseIPv6ifthereisanIPv6addressavailable,andfallbacktoIPv4ifnot.)

IfyouneedtoforcePuTTYtouseaparticularprotocol,youcanexplicitlysetthisto‘IPv4’or‘IPv6’.

4.13.5‘Logicalnameofremotehost’ThisallowsyoutotellPuTTYthatthehostitwillreallyendupconnectingtoisdifferentfromwhereitthinksitismakinganetworkconnection.

Youmightusethis,forinstance,ifyouhadsetupanSSHportforwardinginonePuTTYsessionsothatconnectionstosomearbitraryport(say,localhostport10022)wereforwardedtoasecondmachine'sSSHport(say,foovaxport22),andthenstartedasecondPuTTYconnectingtotheforwardedport.

Innormalusage,thesecondPuTTYwillaccessthehostkeycacheunderthehostnameandportitactuallyconnectedto(i.e.localhostport10022inthisexample).Usingthelogicalhostnameoption,however,youcanconfigurethesecondPuTTYtocachethehostkeyunderthenameofthehostyouknowthatit'sreallygoingtoenduptalkingto(herefoovax).

Thiscanbeusefulifyouexpecttoconnecttothesameactualserverthroughmanydifferentchannels(perhapsbecauseyourportforwardingarrangementskeepchanging):byconsistentlysettingthelogicalhostname,youcanarrangethatPuTTYwillnotkeepaskingyoutoreconfirmitshostkey.Conversely,ifyouexpecttousethesamelocalportnumberforportforwardingstolotsofdifferentservers,youprobablydidn'twantanyparticularserver'shostkeycachedunderthatlocalportnumber.(Forthislattercase,youcouldinsteadexplicitlyconfigurehostkeysintherelevantsessions;seesection4.20.2.)

Ifyoujustenterahostnameforthisoption,PuTTYwillcachetheSSHhostkeyunderthedefaultSSHportforthathost,irrespectiveoftheportyoureallyconnectedto(sincethetypicalscenarioisliketheaboveexample:youconnecttoasillyrealportnumberandyourconnectionendsupforwardedtothenormalport-22SSHserverofsomeothermachine).Tooverridethis,youcanappendaportnumbertothelogicalhostname,separatedbyacolon.E.g.entering‘foovax:2200’asthelogicalhostnamewillcausethehostkeytobecachedasifyouhadconnectedtoport2200offoovax.

Ifyouprovideahostnameusingthisoption,itisalsodisplayedinother

locationswhichcontaintheremotehostname,suchasthedefaultwindowtitleandthedefaultSSHpasswordprompt.Thisreflectsthefactthatthisisthehostyou'rereallyconnectingto,whichismoreimportantthanthemeremeansyouhappentobeusingtocontactthathost.(Thisappliesevenifyou'reusingaprotocolotherthanSSH.)

4.14TheDatapanelTheDatapanelallowsyoutoconfigurevariouspiecesofdatawhichcanbesenttotheservertoaffectyourconnectionatthefarend.

Eachoptiononthispanelappliestomorethanoneprotocol.Optionswhichapplytoonlyoneprotocolappearonthatprotocol'sconfigurationpanels.

4.14.1‘Auto-loginusername’4.14.2Useofsystemusername4.14.3‘Terminal-typestring’4.14.4‘Terminalspeeds’4.14.5Settingenvironmentvariablesontheserver

4.14.1‘Auto-loginusername’AllthreeoftheSSH,TelnetandRloginprotocolsallowyoutospecifywhatusernameyouwanttologinas,withouthavingtotypeitexplicitlyeverytime.(SomeTelnetserversdon'tsupportthis.)

Inthisboxyoucantypethatusername.

4.14.2UseofsystemusernameWhenthepreviousbox(section4.14.1)isleftblank,bydefault,PuTTYwillpromptforausernameatthetimeyoumakeaconnection.

Insomeenvironments,suchasthenetworksoflargeorganisationsimplementingsinglesign-on,amoresensibledefaultmaybetousethenameoftheuserloggedintothelocaloperatingsystem(ifany);thisisparticularlylikelytobeusefulwithGSSAPIauthentication(seesection4.23).Thiscontrolallowsyoutochangethedefaultbehaviour.

Thecurrentsystemusernameisdisplayedinthedialogasaconvenience.Itisnotsavedintheconfiguration;ifasavedsessionislaterusedbyadifferentuser,thatuser'snamewillbeused.

4.14.3‘Terminal-typestring’MostserversyoumightconnecttowithPuTTYaredesignedtobeconnectedtofromlotsofdifferenttypesofterminal.Inordertosendtherightcontrolsequencestoeachone,theserverwillneedtoknowwhattypeofterminalitisdealingwith.Therefore,eachoftheSSH,TelnetandRloginprotocolsallowatextstringtobesentdowntheconnectiondescribingtheterminal.OnaUnixserver,thisselectsanentryfromthetermcaporterminfodatabasethattellsapplicationswhatcontrolsequencestosendtotheterminal,andwhatcharactersequencestoexpectthekeyboardtogenerate.

PuTTYattemptstoemulatetheUnixxtermprogram,andbydefaultitreflectsthisbysendingxtermasaterminal-typestring.Ifyoufindthisisnotdoingwhatyouwant-perhapstheremotesystemreports‘Unknownterminaltype’-youcouldtrysettingthistosomethingdifferent,suchasvt220.

Ifyou'renotsurewhetheraproblemisduetotheterminaltypesettingornot,youprobablyneedtoconsultthemanualforyourapplicationoryourserver.

4.14.4‘Terminalspeeds’TheTelnet,Rlogin,andSSHprotocolsallowtheclienttospecifyterminalspeedstotheserver.

Thisparameterdoesnotaffecttheactualspeedoftheconnection,whichisalways‘asfastaspossible’;itisjustahintthatissometimesusedbyserversoftwaretomodifyitsbehaviour.Forinstance,ifaslowspeedisindicated,theservermayswitchtoalessbandwidth-hungrydisplaymode.

Thevalueisusuallymeaninglessinanetworkenvironment,butPuTTYletsyouconfigureit,incaseyoufindtheserverisreactingbadlytothedefaultvalue.

Theformatisapairofnumbersseparatedbyacomma,forinstance,38400,38400.Thefirstnumberrepresentstheoutputspeed(fromtheserver)inbitspersecond,andthesecondistheinputspeed(totheserver).(OnlythefirstisusedintheRloginprotocol.)

ThisoptionhasnoeffectonRawconnections.

4.14.5SettingenvironmentvariablesontheserverTheTelnetprotocolprovidesameansfortheclienttopassenvironmentvariablestotheserver.ManyTelnetservershavestoppedsupportingthisfeatureduetosecurityflaws,butPuTTYstillsupportsitforthebenefitofanyserverswhichhavefoundotherwaysaroundthesecurityproblemsthanjustdisablingthewholemechanism.

Version2oftheSSHprotocolalsoprovidesasimilarmechanism,whichiseasiertoimplementwithoutsecurityflaws.NewerSSH-2serversaremorelikelytosupportitthanolderones.

ThisconfigurationdataisnotusedintheSSH-1,rloginorrawprotocols.

Toaddanenvironmentvariabletothelisttransmitteddowntheconnection,youenterthevariablenameinthe‘Variable’box,enteritsvalueinthe‘Value’box,andpressthe‘Add’button.Toremoveonefromthelist,selectitinthelistboxandpress‘Remove’.

4.15TheProxypanelTheProxypanelallowsyoutoconfigurePuTTYtousevarioustypesofproxyinordertomakeitsnetworkconnections.ThesettingsinthispanelaffecttheprimarynetworkconnectionformingyourPuTTYsession,andalsoanyextraconnectionsmadeasaresultofSSHportforwarding(seesection3.5).

Notethatunlikesomesoftware(suchaswebbrowsers),PuTTYdoesnotattempttoautomaticallydeterminewhethertouseaproxyand(ifso)whichonetouseforagivendestination.Ifyouneedtouseaproxy,itmustalwaysbeexplicitlyconfigured.

4.15.1Settingtheproxytype4.15.2Excludingpartsofthenetworkfromproxying4.15.3Nameresolutionwhenusingaproxy4.15.4Usernameandpassword4.15.5SpecifyingtheTelnetorLocalproxycommand4.15.6Controllingproxylogging

4.15.1SettingtheproxytypeThe‘Proxytype’radiobuttonsallowyoutoconfigurewhattypeofproxyyouwantPuTTYtouseforitsnetworkconnections.Thedefaultsettingis‘None’;inthismodenoproxyisusedforanyconnection.

Selecting‘HTTP’allowsyoutoproxyyourconnectionsthroughawebserversupportingtheHTTPCONNECTcommand,asdocumentedinRFC2817.Selecting‘SOCKS4’or‘SOCKS5’allowsyoutoproxyyourconnectionsthroughaSOCKSserver.ManyfirewallsimplementalessformaltypeofproxyinwhichausercanmakeaTelnetconnectiondirectlytothefirewallmachineandenteracommandsuchasconnectmyhost.com22toconnectthroughtoanexternalhost.Selecting‘Telnet’allowsyoutotellPuTTYtousethistypeofproxy.Selecting‘Local’allowsyoutospecifyanarbitrarycommandonthelocalmachinetoactasaproxy.Whenthesessionisstarted,insteadofcreatingaTCPconnection,PuTTYrunsthecommand(specifiedinsection4.15.5),andusesitsstandardinputandoutputstreams.

Thiscouldbeused,forinstance,totalktosomekindofnetworkproxythatPuTTYdoesnotnativelysupport;oryoucouldtunnelaconnectionoversomethingotherthanTCP/IPentirely.

IfyouwantyourlocalproxycommandtomakeasecondarySSHconnectiontoaproxyhostandthentunneltheprimaryconnectionoverthat,youmightwellwantthe-nccommand-lineoptioninPlink.Seesection3.8.3.14formoreinformation.

Youcanalsoenablethismodeonthecommandline;seesection3.8.3.24.

4.15.2ExcludingpartsofthenetworkfromproxyingTypicallyyouwillonlyneedtouseaproxytoconnecttonon-localpartsofyournetwork;forexample,yourproxymightberequiredforconnectionsoutsideyourcompany'sinternalnetwork.Inthe‘ExcludeHosts/IPs’boxyoucanenterrangesofIPaddresses,orrangesofDNSnames,forwhichPuTTYwillavoidusingtheproxyandmakeadirectconnectioninstead.

The‘ExcludeHosts/IPs’boxmaycontainmorethanoneexclusionrange,separatedbycommas.EachrangecanbeanIPaddressoraDNSname,witha*characterallowingwildcards.Forexample:

*.example.com

Thisexcludesanyhostwithanameendingin.example.comfromproxying.

192.168.88.*

ThisexcludesanyhostwithanIPaddressstartingwith192.168.88fromproxying.

192.168.88.*,*.example.com

Thisexcludesbothoftheaboverangesatonce.

Connectionstothelocalhost(thehostnamelocalhost,andanyloopbackIPaddress)areneverproxied,eveniftheproxyexcludelistdoesnotexplicitlycontainthem.Itisveryunlikelythatthisbehaviourwouldevercauseproblems,butifitdoesyoucanchangeitbyenabling‘Considerproxyinglocalhostconnections’.

NotethatifyouaredoingDNSattheproxy(seesection4.15.3),youshouldmakesurethatyourproxyexclusionsettingsdonotdependonknowingtheIPaddressofahost.IfthenameispassedontotheproxywithoutPuTTYlookingitup,itwillneverknowtheIPaddressandcannotcheckitagainstyourlist.

4.15.3NameresolutionwhenusingaproxyIfyouareusingaproxytoaccessaprivatenetwork,itcanmakeadifferencewhetherDNSnameresolutionisperformedbyPuTTYitself(ontheclientmachine)orperformedbytheproxy.

The‘DoDNSnamelookupatproxyend’configurationoptionallowsyoutocontrolthis.Ifyousetitto‘No’,PuTTYwillalwaysdoitsownDNS,andwillalwayspassanIPaddresstotheproxy.Ifyousetitto‘Yes’,PuTTYwillalwayspasshostnamesstraighttotheproxywithouttryingtolookthemupfirst.

Ifyousetthisoptionto‘Auto’(thedefault),PuTTYwilldosomethingitconsidersappropriateforeachtypeofproxy.Telnet,HTTP,andSOCKS5proxieswillhavehostnamespassedstraighttothem;SOCKS4proxieswillnot.

NotethatifyouaredoingDNSattheproxy,youshouldmakesurethatyourproxyexclusionsettings(seesection4.15.2)donotdependonknowingtheIPaddressofahost.IfthenameispassedontotheproxywithoutPuTTYlookingitup,itwillneverknowtheIPaddressandcannotcheckitagainstyourlist.

TheoriginalSOCKS4protocoldoesnotsupportproxy-sideDNS.Thereisaprotocolextension(SOCKS4A)whichdoessupportit,butnotallSOCKS4serversprovidethisextension.IfyouenableproxyDNSandyourSOCKS4servercannotdealwithit,thismightbewhy.

4.15.4UsernameandpasswordIfyourproxyrequiresauthentication,youcanenterausernameandapasswordinthe‘Username’and‘Password’boxes.

Notethatifyousaveyoursession,theproxypasswordwillbesavedinplaintext,soanyonewhocanaccessyourPuTTYconfigurationdatawillbeabletodiscoverit.

Authenticationisnotfullysupportedforallformsofproxy:

UsernameandpasswordauthenticationissupportedforHTTPproxiesandSOCKS5proxies.

WithSOCKS5,authenticationisviaCHAPiftheproxysupportsit(thisisnotsupportedinPuTTYtel);otherwisethepasswordissenttotheproxyinplaintext.WithHTTPproxying,theonlycurrentlysupportedauthenticationmethodis‘basic’,wherethepasswordissenttotheproxyinplaintext.

SOCKS4canusethe‘Username’field,butdoesnotsupportpasswords.YoucanspecifyawaytoincludeausernameandpasswordintheTelnet/Localproxycommand(seesection4.15.5).

4.15.5SpecifyingtheTelnetorLocalproxycommandIfyouareusingtheTelnetproxytype,theusualcommandrequiredbythefirewall'sTelnetserverisconnect,followedbyahostnameandaportnumber.Ifyourproxyneedsadifferentcommand,youcanenteranalternativehere.

IfyouareusingtheLocalproxytype,thelocalcommandtorunisspecifiedhere.

Inthisstring,youcanuse\ntorepresentanew-line,\rtorepresentacarriagereturn,\ttorepresentatabcharacter,and\xfollowedbytwohexdigitstorepresentanyothercharacter.\\isusedtoencodethe\characteritself.

Also,thespecialstrings%hostand%portwillbereplacedbythehostnameandportnumberyouwanttoconnectto.Thestrings%userand%passwillbereplacedbytheproxyusernameandpasswordyouspecify.Thestrings%proxyhostand%proxyportwillbereplacedbythehostdetailsspecifiedontheProxypanel,ifany(thisismostlikelytobeusefulfortheLocalproxytype).Togetaliteral%sign,enter%%.

IfaTelnetproxyserverpromptsforausernameandpasswordbeforecommandscanbesent,youcanuseacommandsuchas:

%user\n%pass\nconnect%host%port\n

Thiswillsendyourusernameandpasswordasthefirsttwolinestotheproxy,followedbyacommandtoconnecttothedesiredhostandport.Notethatifyoudonotincludethe%useror%passtokensintheTelnetcommand,thenthe‘Username’and‘Password’configurationfieldswillbeignored.

4.15.6ControllingproxyloggingOftentheproxyinteractionhasitsowndiagnosticoutput;thisisparticularlythecaseforlocalproxycommands.

Thesetting‘Printproxydiagnosticsintheterminalwindow’letsyoucontrolhowmuchoftheproxy'sdiagnosticsareprintedtothemainterminalwindow,alongwithoutputfromyourmainsession.

Bydefault(‘No’),proxydiagnosticsareonlysenttotheEventLog;with‘Yes’theyarealsoprintedtotheterminal,wheretheymaygetmixedupwithyourmainsession.‘Onlyuntilsessionstarts’isacompromise;proxymessageswillgototheterminalwindowuntilthemainsessionisdeemedtohavestarted(inaprotocol-dependentway),whichiswhenthey'remostlikelytobeinteresting;anyfurtherproxy-relatedmessagesduringthesessionwillonlygototheEventLog.

4.16TheTelnetpanelTheTelnetpanelallowsyoutoconfigureoptionsthatonlyapplytoTelnetsessions.

4.16.1‘HandlingofOLD_ENVIRONambiguity’4.16.2PassiveandactiveTelnetnegotiationmodes4.16.3‘KeyboardsendsTelnetspecialcommands’4.16.4‘ReturnkeysendsTelnetNewLineinsteadof^M’

4.16.1‘HandlingofOLD_ENVIRONambiguity’TheoriginalTelnetmechanismforpassingenvironmentvariableswasbadlyspecified.Atthetimethestandard(RFC1408)waswritten,BSDtelnetimplementationswerealreadysupportingthefeature,andtheintentionofthestandardwastodescribethebehaviourtheBSDimplementationswerealreadyusing.

Sadlytherewasatypingerrorinthestandardwhenitwasissued,andtwovitalfunctioncodeswerespecifiedthewrongwayround.BSDimplementationsdidnotchange,andthestandardwasnotcorrected.Therefore,it'spossibleyoumightfindeitherBSDorRFC-compliantimplementationsoutthere.ThisswitchallowsyoutochoosewhichonePuTTYclaimstobe.

Theproblemwassolvedbyissuingasecondstandard,defininganewTelnetmechanismcalledNEW_ENVIRON,whichbehavedexactlyliketheoriginalOLD_ENVIRONbutwasnotencumberedbyexistingimplementations.MostTelnetserversnowsupportthis,andit'sunambiguous.Thisfeatureshouldonlybeneededifyouhavetroublepassingenvironmentvariablestoquiteanoldserver.

4.16.2PassiveandactiveTelnetnegotiationmodesInaTelnetconnection,therearetwotypesofdatapassedbetweentheclientandtheserver:actualtext,andnegotiationsaboutwhichTelnetextrafeaturestouse.

PuTTYcanusetwodifferentstrategiesfornegotiation:

Inactivemode,PuTTYstartstosendnegotiationsassoonastheconnectionisopened.Inpassivemode,PuTTYwillwaittonegotiateuntilitseesanegotiationfromtheserver.

Theobviousdisadvantageofpassivemodeisthatiftheserverisalsooperatinginapassivemode,thennegotiationwillneverbeginatall.ForthisreasonPuTTYdefaultstoactivemode.

However,sometimespassivemodeisrequiredinordertosuccessfullygetthroughcertaintypesoffirewallandTelnetproxyserver.Ifyouhaveconfusingtroublewithafirewall,youcouldtryenablingpassivemodetoseeifithelps.

4.16.3‘KeyboardsendsTelnetspecialcommands’Ifthisboxischecked,severalkeysequenceswillhavetheirnormalactionsmodified:

theBackspacekeyonthekeyboardwillsendtheTelnetspecialbackspacecode;Control-CwillsendtheTelnetspecialInterruptProcesscode;Control-ZwillsendtheTelnetspecialSuspendProcesscode.

Youprobablyshouldn'tenablethisunlessyouknowwhatyou'redoing.

4.16.4‘ReturnkeysendsTelnetNewLineinsteadof^M’Unlikemostotherremoteloginprotocols,theTelnetprotocolhasaspecial‘newline’codethatisnotthesameastheusuallineendingsofControl-MorControl-J.Bydefault,PuTTYsendstheTelnetNewLinecodewhenyoupressReturn,insteadofsendingControl-Masitdoesinmostotherprotocols.

MostUnix-styleTelnetserversdon'tmindwhethertheyreceiveTelnetNewLineorControl-M;someserversdoexpectNewLine,andsomeserversprefertosee^M.IfyouareseeingsurprisingbehaviourwhenyoupressReturninaTelnetsession,youmighttryturningthisoptionofftoseeifithelps.

4.17TheRloginpanelTheRloginpanelallowsyoutoconfigureoptionsthatonlyapplytoRloginsessions.

4.17.1‘Localusername’

4.17.1‘Localusername’Rloginallowsanautomated(password-free)formofloginbymeansofafilecalled.rhostsontheserver.Youputalineinyour.rhostsfilesayingsomethinglikejbloggs@pc1.example.com,andthenwhenyoumakeanRloginconnectiontheclienttransmitstheusernameoftheuserrunningtheRloginclient.Theservercheckstheusernameandhostnameagainst.rhosts,andiftheymatchitdoesnotaskforapassword.

ThisonlyworksbecauseUnixsystemscontainasafeguardtostopauserfrompretendingtobeanotheruserinanRloginconnection.Rloginconnectionshavetocomefromportnumbersbelow1024,andUnixsystemsprohibitthistounprivilegedprocesses;sowhentheserverseesaconnectionfromalow-numberedport,itassumestheclientendoftheconnectionisheldbyaprivileged(andthereforetrusted)process,soitbelievestheclaimofwhotheuseris.

Windowsdoesnothavethisrestriction:anyusercaninitiateanoutgoingconnectionfromalow-numberedport.Hence,theRlogin.rhostsmechanismiscompletelyuselessforsecurelydistinguishingseveraldifferentusersonaWindowsmachine.Ifyouhavea.rhostsentrypointingataWindowsPC,youshouldassumethatanyoneusingthatPCcanspoofyourusernameinanRloginconnectionandaccessyouraccountontheserver.

The‘Localusername’controlallowsyoutospecifywhatusernamePuTTYshouldclaimyouhave,incaseitdoesn'tmatchyourWindowsusername(orincaseyoudidn'tbothertosetupaWindowsusername).

4.18TheSSHpanelTheSSHpanelallowsyoutoconfigureoptionsthatonlyapplytoSSHsessions.

4.18.1Executingaspecificcommandontheserver4.18.2‘Don'tstartashellorcommandatall’4.18.3‘Enablecompression’4.18.4‘SSHprotocolversion’4.18.5SharinganSSHconnectionbetweenPuTTYtools

4.18.1ExecutingaspecificcommandontheserverInSSH,youdon'thavetorunageneralshellsessionontheserver.Instead,youcanchoosetorunasinglespecificcommand(suchasamailuseragent,forexample).Ifyouwanttodothis,enterthecommandinthe‘Remotecommand’box.

Notethatmostserverswillclosethesessionafterexecutingthecommand.

4.18.2‘Don'tstartashellorcommandatall’Ifyoutickthisbox,PuTTYwillnotattempttorunashellorcommandafterconnectingtotheremoteserver.YoumightwanttousethisoptionifyouareonlyusingtheSSHconnectionforportforwarding,andyouruseraccountontheserverdoesnothavetheabilitytorunashell.

ThisfeatureisonlyavailableinSSHprotocolversion2(sincetheversion1protocolassumesyouwillalwayswanttorunashell).

Thisfeaturecanalsobeenabledusingthe-Ncommand-lineoption;seesection3.8.3.13.

IfyouusethisfeatureinPlink,youwillnotbeabletoterminatethePlinkprocessbyanygracefulmeans;theonlywaytokillitwillbebypressingControl-Corsendingakillsignalfromanotherprogram.

4.18.3‘Enablecompression’ThisenablesdatacompressionintheSSHconnection:datasentbytheserveriscompressedbeforesending,anddecompressedattheclientend.Likewise,datasentbyPuTTYtotheserveriscompressedfirstandtheserverdecompressesitattheotherend.Thiscanhelpmakethemostofalow-bandwidthconnection.

4.18.4‘SSHprotocolversion’ThisallowsyoutoselectwhethertouseSSHprotocolversion2ortheolderversion1.

Youshouldnormallyleavethisatthedefaultof‘2’.Aswellashavingfewerfeatures,theolderSSH-1protocolisnolongerdeveloped,hasmanyknowncryptographicweaknesses,andisgenerallynotconsideredtobesecure.PuTTY'sprotocol1implementationisprovidedmainlyforcompatibility,andisnolongerbeingenhanced.

Ifaserveroffersbothversions,prefer‘2’.IfyouhavesomeserverorpieceofequipmentthatonlytalksSSH-1,select‘1’here,anddonottreattheresultingconnectionassecure.

PuTTYwillnotautomaticallyfallbacktotheotherversionoftheprotocoliftheserverturnsoutnottomatchyourselectionhere;instead,itwillputupanerrormessageandaborttheconnection.ThispreventsanactiveattackerdowngradinganintendedSSH-2connectiontoSSH-1.

4.18.5SharinganSSHconnectionbetweenPuTTYtoolsThecontrolsinthisboxallowyoutoconfigurePuTTYtoreuseanexistingSSHconnection,wherepossible.

TheSSH-2protocolpermitsyoutorunmultipledatachannelsoverthesameSSHconnection,sothatyoucanloginjustonce(anddotheexpensiveencryptionsetupjustonce)andthenhavemorethanoneterminalwindowopen.

EachinstanceofPuTTYcanstillrunatmostoneterminalsession,butusingthecontrolsinthisbox,youcanconfigurePuTTYtocheckifanotherinstanceofitselfhasalreadyconnectedtothetargethost,andifso,sharethatinstance'sSSHconnectioninsteadofstartingaseparatenewone.

Toenablethisfeature,justtickthebox‘ShareSSHconnectionsifpossible’.Then,wheneveryoustartupaPuTTYsessionconnectingtoaparticularhost,itwilltrytoreuseanexistingSSHconnectionifoneisavailable.Forexample,selecting‘DuplicateSession’fromthesystemmenuwilllaunchanothersessiononthesamehost,andifsharingisenabledthenitwillreusetheexistingSSHconnection.

Whenthismodeisinuse,thefirstPuTTYthatconnectedtoagivenserverbecomesthe‘upstream’,whichmeansthatitistheonemanagingtherealSSHconnection.AllsubsequentPuTTYswhichreusetheconnectionarereferredtoas‘downstreams’:theydonotconnecttotherealserveratall,butinsteadconnecttotheupstreamPuTTYvialocalinter-processcommunicationmethods.

Forthissystemtobeactivated,boththeupstreamanddownstreaminstancesofPuTTYmusthavethesharingoptionenabled.

TheupstreamPuTTYcanthereforenotterminateuntilallitsdownstreamshaveclosed.ThisissimilartotheeffectyougetwithportforwardingorX11forwarding,inwhichaPuTTYwhoseterminalsessionhasalreadyfinishedwillstillremainopensoastokeepserving

forwardedconnections.

Incaseyouneedtoconfigurethissysteminmoredetail,therearetwoadditionalcheckboxeswhichallowyoutospecifywhetheraparticularPuTTYcanactasanupstreamoradownstreamorboth.(Theseboxesonlytakeeffectifthemain‘ShareSSHconnectionsifpossible’boxisalsoticked.)Bydefaultbothoftheseboxesareticked,sothatmultiplePuTTYsstartedfromthesameconfigurationwilldesignateoneofthemselvesastheupstreamandshareasingleconnection;butifforsomereasonyouneedaparticularPuTTYconfigurationnottobeanupstream(e.g.becauseyoudefinitelyneedittoclosepromptly)ornottobeadownstream(e.g.becauseitneedstodoitsownauthenticationusingaspecialprivatekey)thenyoucanuntickoneortheotheroftheseboxes.

Ihavereferredto‘PuTTY’throughouttheabovediscussion,butalltheotherPuTTYtoolswhichmakeSSHconnectionscanusethismechanismtoo.Forexample,ifPSCPorPSFTPloadsaconfigurationwithsharingenabled,thenitcanactasadownstreamanduseanexistingSSHconnectionsetupbyaninstanceofGUIPuTTY.TheonespecialcaseisthatPSCPandPSFTPwillneveractasupstreams.

ItispossibletotestprogrammaticallyfortheexistenceofaliveupstreamusingPlink.Seesection7.2.3.3.

4.19TheKexpanelTheKexpanel(shortfor‘keyexchange’)allowsyoutoconfigureoptionsrelatedtoSSH-2keyexchange.

KeyexchangeoccursatthestartofanSSHconnection(andoccasionallythereafter);itestablishesasharedsecretthatisusedasthebasisforallofSSH'ssecurityfeatures.Itisthereforeveryimportantforthesecurityoftheconnectionthatthekeyexchangeissecure.

Keyexchangeisacryptographicallyintensiveprocess;ifeithertheclientortheserverisarelativelyslowmachine,theslowermethodsmaytakeseveraltensofsecondstocomplete.

Ifconnectionstartupistooslow,ortheconnectionhangsperiodically,youmaywanttotrychangingthesesettings.

Ifyoudon'tunderstandwhatanyofthismeans,it'ssafetoleavethesesettingsalone.

ThisentirepanelisonlyrelevanttoSSHprotocolversion2;noneofthesesettingsaffectSSH-1atall.

4.19.1Keyexchangealgorithmselection4.19.2Repeatkeyexchange

4.19.1KeyexchangealgorithmselectionPuTTYsupportsavarietyofSSH-2keyexchangemethods,andallowsyoutochoosewhichoneyouprefertouse;configurationissimilartocipherselection(seesection4.21).

PuTTYcurrentlysupportsthefollowingkeyexchangemethods:

‘ECDH’:ellipticcurveDiffie-Hellmankeyexchange.‘Group14’:Diffie-Hellmankeyexchangewithawell-known2048-bitgroup.‘Group1’:Diffie-Hellmankeyexchangewithawell-known1024-bitgroup.Wenolongerrecommendusingthismethod,andit'snotusedbydefaultinnewinstallations;however,itmaybetheonlymethodsupportedbyveryoldserversoftware.‘Groupexchange’:withthismethod,insteadofusingafixedgroup,PuTTYrequeststhattheserversuggestagrouptouseforkeyexchange;theservercanavoidgroupsknowntobeweak,andpossiblyinventnewonesovertime,withoutanychangesrequiredtoPuTTY'sconfiguration.Werecommenduseofthismethodinsteadofthewell-knowngroups,ifpossible.‘RSAkeyexchange’:thisrequiresmuchlesscomputationaleffortonthepartoftheclient,andsomewhatlessonthepartoftheserver,thanDiffie-Hellmankeyexchange.

IfthefirstalgorithmPuTTYfindsisbelowthe‘warnbelowhere’line,youwillseeawarningboxwhenyoumaketheconnection,similartothatforcipherselection(seesection4.21).

4.19.2RepeatkeyexchangeIfthesessionkeynegotiatedatconnectionstartupisusedtoomuchorfortoolong,itmaybecomefeasibletomountattacksagainsttheSSHconnection.Therefore,theSSH-2protocolspecifiesthatanewkeyexchangeshouldtakeplaceeverysooften;thiscanbeinitiatedbyeithertheclientortheserver.

Whilethisrenegotiationistakingplace,nodatacanpassthroughtheSSHconnection,soitmayappearto‘freeze’.(TheoccurrenceofrepeatkeyexchangeisnotedintheEventLog;seesection3.1.3.1.)Usuallythesamealgorithmisusedasatthestartoftheconnection,withasimilaroverhead.

TheseoptionscontrolhowoftenPuTTYwillinitiatearepeatkeyexchange(‘rekey’).YoucanalsoforceakeyexchangeatanytimefromtheSpecialCommandsmenu(seesection3.1.3.2).

‘Maxminutesbeforerekey’specifiestheamountoftimethatisallowedtoelapsebeforearekeyisinitiated.Ifthisissettozero,PuTTYwillnotrekeyduetoelapsedtime.TheSSH-2protocolspecificationrecommendsatimeoutofatmost60minutes.

Youmighthaveaneedtodisabletime-basedrekeyscompletelyforthesamereasonsthatkeepalivesaren'talwayshelpful.IfyouanticipatesufferinganetworkdropoutofseveralhoursinthemiddleofanSSHconnection,butwerenotactuallyplanningtosenddatadownthatconnectionduringthosehours,thenanattemptedrekeyinthemiddleofthedropoutwillprobablycausetheconnectiontobeabandoned,whereasifrekeysaredisabledthentheconnectionshouldinprinciplesurvive(intheabsenceofinterferingfirewalls).Seesection4.13.1formorediscussionoftheseissues;forthesepurposes,rekeyshavemuchthesamepropertiesaskeepalives.(Exceptthatrekeyshavecryptographicvalueinthemselves,soyoushouldbearthatinmindwhendecidingwhethertoturnthemoff.)Note,however,thetheSSHservercanstillinitiaterekeys.

‘Maxdatabeforerekey’specifiestheamountofdata(inbytes)thatis

permittedtoflowineitherdirectionbeforearekeyisinitiated.Ifthisissettozero,PuTTYwillnotrekeyduetotransferreddata.TheSSH-2protocolspecificationrecommendsalimitofatmost1gigabyte.

Aswellasspecifyingavalueinbytes,thefollowingshorthandcanbeused:

‘1k’specifies1kilobyte(1024bytes).‘1M’specifies1megabyte(1024kilobytes).‘1G’specifies1gigabyte(1024megabytes).

Disablingdata-basedrekeysentirelyisabadidea.Theintegrity,andtoalesserextent,confidentialityoftheSSH-2protocoldependinpartonrekeysoccurringbeforea32-bitpacketsequencenumberwrapsaround.Unliketime-basedrekeys,data-basedrekeyswon'toccurwhentheSSHconnectionisidle,sotheyshouldn'tcausethesameproblems.TheSSH-1protocol,incidentally,hasevenweakerintegrityprotectionthanSSH-2withoutrekeys.

4.20TheHostKeyspanelTheHostKeyspanelallowsyoutoconfigureoptionsrelatedtoSSH-2hostkeymanagement.

Hostkeysareusedtoprovetheserver'sidentity,andassureyouthattheserverisnotbeingspoofed(eitherbyaman-in-the-middleattackorbycompletelyreplacingitonthenetwork).Seesection2.2forabasicintroductiontohostkeys.

ThisentirepanelisonlyrelevanttoSSHprotocolversion2;noneofthesesettingsaffectSSH-1atall.

4.20.1Hostkeytypeselection4.20.2Manuallyconfiguringhostkeys

4.20.1HostkeytypeselectionPuTTYsupportsavarietyofSSH-2hostkeytypes,andallowsyoutochoosewhichoneyouprefertousetoidentifytheserver.Configurationissimilartocipherselection(seesection4.21).

PuTTYcurrentlysupportsthefollowinghostkeytypes:

‘Ed25519’:Edwards-curveDSAusingatwistedEdwardscurvewithmodulus2^255-19.‘ECDSA’:ellipticcurveDSAusingoneoftheNIST-standardisedellipticcurves.‘DSA’:straightforwardDSAusingmodularexponentiation.‘RSA’:theordinaryRSAalgorithm.

IfPuTTYalreadyhasoneormorehostkeysstoredfortheserver,itwillprefertouseoneofthose,eveniftheserverhasakeytypethatishigherinthepreferenceorder.YoucanaddsuchakeytoPuTTY'scachefromwithinanexistingsessionusingthe‘SpecialCommands’menu;seesection3.1.3.2.

Otherwise,PuTTYwillchooseakeytypebasedpurelyonthepreferenceorderyouspecifyintheconfiguration.

IfthefirstkeytypePuTTYfindsisbelowthe‘warnbelowhere’line,youwillseeawarningboxwhenyoumaketheconnection,similartothatforcipherselection(seesection4.21).

4.20.2ManuallyconfiguringhostkeysInsomesituations,ifPuTTY'sautomatedhostkeymanagementisnotdoingwhatyouneed,youmightneedtomanuallyconfigurePuTTYtoacceptaspecifichostkey,oroneofaspecificsetofhostkeys.

OnereasonwhyyoumightwanttodothisisbecausethehostnamePuTTYisconnectingtoisusinground-robinDNStoreturnoneofmultipleactualservers,andtheyallhavedifferenthostkeys.Inthatsituation,youmightneedtoconfigurePuTTYtoacceptanyofalistofhostkeysforthepossibleservers,whilestillrejectinganykeynotinthatlist.

AnotherreasonisifPuTTY'sautomatedhostkeymanagementiscompletelyunavailable,e.g.becausePuTTY(orPlinkorPSFTP,etc)isrunninginaWindowsenvironmentwithoutaccesstotheRegistry.Inthatsituation,youwillprobablywanttousethe-hostkeycommand-lineoptiontoconfiguretheexpectedhostkey(s);seesection3.8.3.20.

ForsituationswherePuTTY'sautomatedhostkeymanagementsimplypicksthewronghostnametostoreakeyunder,youmaywanttoconsidersettinga‘logicalhostname’instead;seesection4.13.5.

ToconfiguremanualhostkeysviatheGUI,entersometextdescribingthehostkeyintotheeditboxinthe‘Manuallyconfigurehostkeysforthisconnection’container,andpressthe‘Add’button.Thetextwillappearinthe‘Hostkeysorfingerprintstoaccept’listbox.Youcanremovekeysagainwiththe‘Remove’button.

Thetextdescribingahostkeycanbeinoneofthefollowingformats:

AnMD5-basedhostkeyfingerprintoftheformdisplayedinPuTTY'sEventLogandhostkeydialogboxes,i.e.sixteen2-digithexnumbersseparatedbycolons.Abase64-encodedblobdescribinganSSH-2publickeyinOpenSSH'sone-linepublickeyformat.Howyouacquireapublickeyinthisformatisserver-dependent;onanOpenSSHserveritcantypicallybefoundinalocationlike/etc/ssh/ssh_host_rsa_key.pub.

IfthisboxcontainsatleastonehostkeyorfingerprintwhenPuTTYmakesanSSHconnection,thenPuTTY'sautomatedhostkeymanagementiscompletelybypassed:theconnectionwillbepermittedifandonlyifthehostkeypresentedbytheserverisoneofthekeyslistedinthisbox,andthehostkeystoreintheRegistrywillbeneitherreadnorwritten,unlessyouexplicitlydoso.

Iftheboxisempty(asitusuallyis),thenPuTTY'sautomatedhostkeymanagementwillworkasnormal.

4.21TheCipherpanelPuTTYsupportsavarietyofdifferentencryptionalgorithms,andallowsyoutochoosewhichoneyouprefertouse.Youcandothisbydraggingthealgorithmsupanddowninthelistbox(ormovingthemusingtheUpandDownbuttons)tospecifyapreferenceorder.WhenyoumakeanSSHconnection,PuTTYwillsearchdownthelistfromthetopuntilitfindsanalgorithmsupportedbytheserver,andthenusethat.

PuTTYcurrentlysupportsthefollowingalgorithms:

ChaCha20-Poly1305,acombinedcipherandMAC(SSH-2only)AES(Rijndael)-256,192,or128-bitSDCTRorCBC(SSH-2only)Arcfour(RC4)-256or128-bitstreamcipher(SSH-2only)Blowfish-256-bitSDCTR(SSH-2only)or128-bitCBCTriple-DES-168-bitSDCTR(SSH-2only)orCBCSingle-DES-56-bitCBC(seebelowforSSH-2)

IfthealgorithmPuTTYfindsisbelowthe‘warnbelowhere’line,youwillseeawarningboxwhenyoumaketheconnection:

Thefirstciphersupportedbytheserver

issingle-DES,whichisbelowtheconfigured

warningthreshold.

Doyouwanttocontinuewiththisconnection?

Thiswarnsyouthatthefirstavailableencryptionisnotaverysecureone.Typicallyyouwouldputthe‘warnbelowhere’linebetweentheencryptionsyouconsidersecureandtheonesyouconsidersubstandard.Bydefault,PuTTYsuppliesapreferenceorderintendedtoreflectareasonablepreferenceintermsofsecurityandspeed.

InSSH-2,theencryptionalgorithmisnegotiatedindependentlyforeachdirectionoftheconnection,althoughPuTTYdoesnotsupportseparateconfigurationofthepreferenceorders.Asaresultyoumaygettwowarningssimilartotheoneabove,possiblywithdifferentencryptions.

Single-DESisnotrecommendedintheSSH-2protocolstandards,butoneortwoserverimplementationsdosupportit.PuTTYcanusesingle-

DEStointeroperatewiththeseserversifyouenablethe‘Enablelegacyuseofsingle-DESinSSH-2’option;bydefaultthisisdisabledandPuTTYwillsticktorecommendedciphers.

4.22TheAuthpanelTheAuthpanelallowsyoutoconfigureauthenticationoptionsforSSHsessions.

4.22.1‘Displaypre-authenticationbanner’4.22.2‘Bypassauthenticationentirely’4.22.3‘AttemptauthenticationusingPageant’4.22.4‘AttemptTISorCryptoCardauthentication’4.22.5‘Attemptkeyboard-interactiveauthentication’4.22.6‘Allowagentforwarding’4.22.7‘AllowattemptedchangesofusernameinSSH-2’4.22.8‘Privatekeyfileforauthentication’

4.22.1‘Displaypre-authenticationbanner’SSH-2serverscanprovideamessageforclientstodisplaytotheprospectiveuserbeforetheuserlogsin;thisissometimesknownasapre-authentication‘banner’.Typicallythisisusedtoprovideinformationabouttheserverandlegalnotices.

Bydefault,PuTTYdisplaysthismessagebeforepromptingforapasswordorsimilarcredentials(although,unfortunately,notbeforepromptingforaloginname,duetothenatureoftheprotocoldesign).Byuncheckingthisoption,displayofthebannercanbesuppressedentirely.

4.22.2‘Bypassauthenticationentirely’InSSH-2,itisinprinciplepossibletoestablishaconnectionwithoutusingSSH'smechanismstoidentifyorprovewhoyouaretotheserver.AnSSHservercouldprefertohandleauthenticationinthedatachannel,forinstance,orsimplyrequirenouserauthenticationwhatsoever.

Bydefault,PuTTYassumestheserverrequiresauthentication(we'veneverheardofonethatdoesn't),andthusmuststartthisprocesswithausername.Ifyoufindyouaregettingusernamepromptsthatyoucannotanswer,youcouldtryenablingthisoption.However,mostSSHserverswillrejectthis.

ThisisnottheoptionyouwantifyouhaveausernameandjustwantPuTTYtorememberit;forthatseesection4.14.1.It'salsoprobablynotwhatifyou'retryingtosetuppasswordlesslogintoamainstreamSSHserver;dependingontheserver,youprobablywantedpublic-keyauthentication(chapter8)orperhapsGSSAPIauthentication(section4.23).(Thesearestillformsofauthentication,evenifyoudon'thavetointeractwiththem.)

ThisoptiononlyaffectsSSH-2connections.SSH-1connectionsalwaysrequireanauthenticationstep.

4.22.3‘AttemptauthenticationusingPageant’Ifthisoptionisenabled,thenPuTTYwilllookforPageant(theSSHprivate-keystorageagent)andattempttoauthenticatewithanysuitablepublickeysPageantcurrentlyholds.

Thisbehaviourisalmostalwaysdesirable,andisthereforeenabledbydefault.Inrarecasesyoumightneedtoturnitoffinordertoforceauthenticationbysomenon-public-keymethodsuchaspasswords.

Thisoptioncanalsobecontrolledusingthe-noagentcommand-lineoption.Seesection3.8.3.9.

Seechapter9formoreinformationaboutPageantingeneral.

4.22.4‘AttemptTISorCryptoCardauthentication’TISandCryptoCardauthenticationare(despitetheirnames)genericformsofsimplechallenge/responseauthenticationavailableinSSHprotocolversion1only.YoumightusethemifyouwereusingS/Keyone-timepasswords,forexample,orifyouhadaphysicalsecuritytokenthatgeneratedresponsestoauthenticationchallenges.Theycanevenbeusedtopromptforsimplepasswords.

Withthisswitchenabled,PuTTYwillattempttheseformsofauthenticationiftheserveriswillingtotrythem.Youwillbepresentedwithachallengestring(whichmaybedifferenteverytime)andmustsupplythecorrectresponseinordertologin.Ifyourserversupportsthis,youshouldtalktoyoursystemadministratoraboutpreciselywhatformthesechallengesandresponsestake.

4.22.5‘Attemptkeyboard-interactiveauthentication’TheSSH-2equivalentofTISauthenticationiscalled‘keyboard-interactive’.Itisaflexibleauthenticationmethodusinganarbitrarysequenceofrequestsandresponses;soitisnotonlyusefulforchallenge/responsemechanismssuchasS/Key,butitcanalsobeusedfor(forexample)askingtheuserforanewpasswordwhentheoldonehasexpired.

PuTTYleavesthisoptionenabledbydefault,butsuppliesaswitchtoturnitoffincaseyoushouldhavetroublewithit.

4.22.6‘Allowagentforwarding’ThisoptionallowstheSSHservertoopenforwardedconnectionsbacktoyourlocalcopyofPageant.IfyouarenotrunningPageant,thisoptionwilldonothing.

Seechapter9forgeneralinformationonPageant,andsection9.4forinformationonagentforwarding.Notethatthereisasecurityriskinvolvedwithenablingthisoption;seesection9.5fordetails.

4.22.7‘AllowattemptedchangesofusernameinSSH-2’IntheSSH-1protocol,itisimpossibletochangeusernameafterfailingtoauthenticate.Soifyoumis-typeyourusernameatthePuTTY‘loginas:’prompt,youwillnotbeabletochangeitexceptbyrestartingPuTTY.

TheSSH-2protocoldoesallowchangesofusername,inprinciple,butdoesnotmakeitmandatoryforSSH-2serverstoacceptthem.Inparticular,OpenSSHdoesnotacceptachangeofusername;onceyouhavesentoneusername,itwillrejectattemptstotrytoauthenticateasanotheruser.(DependingontheversionofOpenSSH,itmayquietlyreturnfailureforallloginattempts,oritmaysendanerrormessage.)

Forthisreason,PuTTYwillbydefaultnotpromptyouforyourusernamemorethanonce,incasetheservercomplains.Ifyouknowyourservercancopewithit,youcanenablethe‘Allowattemptedchangesofusername’optiontomodifyPuTTY'sbehaviour.

4.22.8‘Privatekeyfileforauthentication’Thisboxiswhereyouenterthenameofyourprivatekeyfileifyouareusingpublickeyauthentication.Seechapter8forinformationaboutpublickeyauthenticationinSSH.

ThiskeymustbeinPuTTY'snativeformat(*.PPK).IfyouhaveaprivatekeyinanotherformatthatyouwanttousewithPuTTY,seesection8.2.12.

YoucanusetheauthenticationagentPageantsothatyoudonotneedtoexplicitlyconfigureakeyhere;seechapter9.

IfaprivatekeyfileisspecifiedherewithPageantrunning,PuTTYwillfirsttryaskingPageanttoauthenticatewiththatkey,andignoreanyotherkeysPageantmayhave.Ifthatfails,PuTTYwillaskforapassphraseasnormal.Youcanalsospecifyapublickeyfileinthiscase(inRFC4716orOpenSSHformat),asthat'ssufficienttoidentifythekeytoPageant,butofcourseifPageantisn'tpresentPuTTYcan'tfallbacktousingthisfileitself.

4.23TheGSSAPIpanelThe‘GSSAPI’subpanelofthe‘Auth’panelcontrolstheuseofGSSAPIauthentication.Thisisamechanismwhichdelegatestheauthenticationexchangetoalibraryelsewhereontheclientmachine,whichinprinciplecanauthenticateinmanydifferentwaysbutinpracticeisusuallyusedwiththeKerberossinglesign-onprotocoltoimplementpasswordlesslogin.

GSSAPIisonlyavailableintheSSH-2protocol.

ThetopmostcontrolontheGSSAPIsubpanelisthecheckboxlabelled‘AttemptGSSAPIauthentication’.Ifthisisdisabled,GSSAPIwillnotbeattemptedatallandtherestofthispanelisunused.Ifitisenabled,GSSAPIauthenticationwillbeattempted,and(typically)ifyourclientmachinehasvalidKerberoscredentialsloaded,thenPuTTYshouldbeabletoauthenticateautomaticallytoserversthatsupportKerberoslogins.

4.23.1‘AllowGSSAPIcredentialdelegation’4.23.2PreferenceorderforGSSAPIlibraries

4.23.1‘AllowGSSAPIcredentialdelegation’GSSAPIcredentialdelegationisamechanismforpassingonyourKerberos(orother)identitytothesessionontheSSHserver.Ifyouenablethisoption,thennotonlywillPuTTYbeabletologinautomaticallytoaserverthatacceptsyourKerberoscredentials,butalsoyouwillbeabletoconnectoutfromthatservertootherKerberos-supportingservicesandusethesamecredentialsjustasautomatically.

(ThisoptionistheKerberosanalogueofSSHagentforwarding;seesection9.4forsomeinformationonthat.)

Notethat,likeSSHagentforwarding,thereisasecurityimplicationintheuseofthisoption:theadministratoroftheserveryouconnectto,oranyoneelsewhohascrackedtheadministratoraccountonthatserver,couldfakeyouridentitywhenconnectingtofurtherKerberos-supportingservices.However,Kerberossitesaretypicallyrunbyacentralauthority,sotheadministratorofoneserverislikelytoalreadyhaveaccesstotheotherservicestoo;sothiswouldtypicallybelessofariskthanSSHagentforwarding.

4.23.2PreferenceorderforGSSAPIlibrariesGSSAPIisamechanismwhichallowsmorethanoneauthenticationmethodtobeaccessedthroughthesameinterface.Therefore,morethanoneauthenticationlibrarymayexistonyoursystemwhichcanbeaccessedusingGSSAPI.

PuTTYcontainsnativesupportforafewwell-knownsuchlibraries,andwilllookforallofthemonyoursystemandusewhicheveritfinds.Ifmorethanoneexistsonyoursystemandyouneedtouseaspecificone,youcanadjusttheorderinwhichitwillsearchusingthispreferencelistcontrol.

Oneoftheoptionsinthepreferencelististouseauser-specifiedGSSAPIlibrary.IfthelibraryyouwanttouseisnotmentionedbynameinPuTTY'slistofoptions,youcanenteritsfullpathnameinthe‘User-suppliedGSSAPIlibrarypath’field,andmovethe‘User-suppliedGSSAPIlibrary’optioninthepreferencelisttomakesureitisselectedbeforeanythingelse.

OnWindows,suchlibrariesarefileswitha.dllextension,andmusthavebeenbuiltinthesamewayasthePuTTYexecutableyou'rerunning;ifyouhavea32-bitDLL,youmustruna32-bitversionofPuTTY,andthesamewith64-bit(seequestionA.6.10).OnUnix,sharedlibrariesgenerallyhavea.soextension.

4.24TheTTYpanelTheTTYpanelletsyouconfiguretheremotepseudo-terminal.

4.24.1‘Don'tallocateapseudo-terminal’4.24.2Sendingterminalmodes

4.24.1‘Don'tallocateapseudo-terminal’WhenconnectingtoaUnixsystem,mostinteractiveshellsessionsareruninapseudo-terminal,whichallowstheUnixsystemtopretendit'stalkingtoarealphysicalterminaldevicebutallowstheSSHservertocatchallthedatacomingfromthatfakedeviceandsenditbacktotheclient.

Occasionallyyoumightfindyouhaveaneedtorunasessionnotinapseudo-terminal.InPuTTY,thisisgenerallyonlyusefulforveryspecialistpurposes;althoughinPlink(seechapter7)itistheusualwayofworking.

4.24.2SendingterminalmodesTheSSHprotocolallowstheclienttosend‘terminalmodes’fortheremotepseudo-terminal.Theseusuallycontroltheserver'sexpectationofthelocalterminal'sbehaviour.

Ifyourserverdoesnothavesensibledefaultsforthesemodes,youmayfindthatchangingthemherehelps,althoughtheserverisatlibertytoignoreyourchanges.Ifyoudon'tunderstandanyofthis,it'ssafetoleavethesesettingsalone.

(Noneofthesesettingswillhaveanyeffectifnopseudo-terminalisrequestedorallocated.)

Youcanchangewhathappensforaparticularmodebyselectingitinthelist,choosingoneoftheoptionsandspecifyingtheexactvalueifnecessary,andhitting‘Set’.Theeffectoftheoptionsisasfollows:

Ifthe‘Auto’optionisselected,thePuTTYtoolswilldecidewhethertospecifythatmodetotheserver,andifso,willsendasensiblevalue.

PuTTYproperwillsendmodesthatithasanopinionon(currentlyonlythecodefortheBackspacekey,ERASE,andwhetherthecharactersetisUTF-8,IUTF8).PlinkonUnixwillpropagateappropriatemodesfromthelocalterminal,ifany.

If‘Nothing’isselected,novalueforthemodewillbespecifiedtotheserverunderanycircumstances.Ifavalueisspecified,itwillbesenttotheserverunderallcircumstances.Theprecisesyntaxofthevalueboxdependsonthemode.

Bydefault,alloftheavailablemodesarelistedas‘Auto’,whichshoulddotherightthinginmostcircumstances.

Thepreciseeffectofeachsetting,ifany,isuptotheserver.TheirnamescomefromPOSIXandotherUnixsystems,andtheyaremostlikelytohaveausefuleffectonsuchsystems.(Thesearethesamesettingsthatcanusuallybechangedusingthesttycommandonceloggedintosuch

servers.)

Somenotablemodesaredescribedbelow;forfullerexplanations,seeyourserverdocumentation.

ERASEisthecharacterthatwhentypedbytheuserwilldeleteonespacetotheleft.Whensetto‘Auto’(thedefaultsetting),thisfollowsthesettingofthelocalBackspacekeyinPuTTY(seesection4.4.1).

Thisandotherspecialcharactersarespecifiedusing^CnotationforCtrl-C,andsoon.Use^<27>or^<0x1B>tospecifyacharacternumerically,and^~togetaliteral^.Othernon-controlcharactersaredenotedbythemselves.Leavingtheboxentirelyblankindicatesthatnocharactershouldbeassignedtothespecifiedfunction,althoughthismaynotbesupportedbyallservers.

QUITisaspecialcharacterthatusuallyforcefullyendsthecurrentprocessontheserver(SIGQUIT).OnmanyserversitsdefaultsettingisCtrl-backslash(^\),whichiseasytoaccidentallyinvokeonmanykeyboards.Ifthisisgettinginyourway,youmaywanttochangeittoanothercharacterorturnitoffentirely.BooleanmodessuchasECHOandICANONcanbespecifiedinPuTTYinavarietyofways,suchastrue/false,yes/no,and0/1.(Explicitlyspecifyingavalueofnoisdifferentfromnotsendingthemodeatall.)ThebooleanmodeIUTF8signalstotheserverwhethertheterminalcharactersetisUTF-8ornot,forpurposessuchasbasiclineediting;ifthisissetincorrectly,thebackspacekeymayerasethewrongamountoftext,forinstance.However,simplysettingthisisnotusuallysufficientfortheservertouseUTF-8;POSIXserverswillgenerallyalsorequirethelocaletobeset(bysomeserver-dependentmeans),althoughmanynewerinstallationsdefaulttoUTF-8.Also,sincethismodewasaddedtotheSSHprotocolmuchlaterthantheothers,manyservers(particularlyolderservers)donothonourthismodesentoverSSH;indeed,afewpoorly-writtenserversobjecttoitsmerepresence,soyoumayfindyouneedtosetittonotbesentatall.Whensetto‘Auto’,thisfollowsthelocalconfiguredcharacterset(seesection4.10.1).Terminalspeedsareconfiguredelsewhere;seesection4.14.4.

4.25TheX11panelTheX11panelallowsyoutoconfigureforwardingofX11overanSSHconnection.

IfyourserverletsyourunXWindowSystemgraphicalapplications,X11forwardingallowsyoutosecurelygivethoseapplicationsaccesstoalocalXdisplayonyourPC.

ToenableX11forwarding,checkthe‘EnableX11forwarding’box.IfyourXdisplayissomewhereunusual,youwillneedtoenteritslocationinthe‘Xdisplaylocation’box;ifthisisleftblank,PuTTYwilltrytofindasensibledefaultintheenvironment,orusetheprimarylocaldisplay(:0)ifthatfails.

Seesection3.4formoreinformationaboutX11forwarding.

4.25.1RemoteX11authentication4.25.2Xauthorityfileforlocaldisplay

4.25.1RemoteX11authenticationIfyouareusingX11forwarding,thevirtualXservercreatedontheSSHservermachinewillbeprotectedbyauthorisationdata.Thisdataisinvented,andchecked,byPuTTY.

TheusualauthorisationmethodusedforthisiscalledMIT-MAGIC-COOKIE-1.Thisisasimplepassword-styleprotocol:theXclientsendssomecookiedatatotheserver,andtheserverchecksthatitmatchestherealcookie.ThecookiedataissentoveranunencryptedX11connection;soifyouallowaclientonathirdmachinetoaccessthevirtualXserver,thenthecookiewillbesentintheclear.

PuTTYoffersthealternativeprotocolXDM-AUTHORIZATION-1.Thisisacryptographicallyauthenticatedprotocol:thedatasentbytheXclientisdifferenteverytime,anditdependsontheIPaddressandportoftheclient'sendoftheconnectionandisalsostampedwiththecurrenttime.SoaneavesdropperwhocapturesanXDM-AUTHORIZATION-1stringcannotimmediatelyre-useitfortheirownXconnection.

PuTTY'ssupportforXDM-AUTHORIZATION-1isasomewhatexperimentalfeature,andmayencounterseveralproblems:

SomeXclientsprobablydonotevensupportXDM-AUTHORIZATION-1,sotheywillnotknowwhattodowiththedataPuTTYhasprovided.ThisauthenticationmechanismwillonlyworkinSSH-2.InSSH-1,theSSHserverdoesnottelltheclientthesourceaddressofaforwardedconnectioninamachine-readableformat,soit'simpossibletoverifytheXDM-AUTHORIZATION-1data.YoumayfindthisfeaturecausesproblemswithsomeSSHservers,whichwillnotcleanupXDM-AUTHORIZATION-1dataafterasession,sothatifyouthenconnecttothesameserverusingaclientwhichonlydoesMIT-MAGIC-COOKIE-1andareallocatedthesameremotedisplaynumber,youmightfindthatout-of-dateauthenticationdataisstillpresentonyourserverandyourXconnectionsfail.

PuTTY'sdefaultisMIT-MAGIC-COOKIE-1.Ifyouchangeit,youshouldbesureyouknowwhatyou'redoing.

4.25.2XauthorityfileforlocaldisplayIfyouareusingX11forwarding,thelocalXservertowhichyourforwardedconnectionsareeventuallydirectedmayitselfrequireauthorisation.

SomeWindowsXserversdonotrequirethis:theydoauthorisationbysimplermeans,suchasacceptinganyconnectionfromthelocalmachinebutnotfromanywhereelse.However,ifyourXserverdoesrequireauthorisation,thenPuTTYneedstoknowwhatauthorisationisrequired.

OnewayinwhichthisdatamightbemadeavailableisfortheXservertostoreitsomewhereinafilewhichhasthesameformatastheUnix.Xauthorityfile.IfthisishowyourWindowsXserverworks,thenyoucantellPuTTYwheretofindthisfilebyconfiguringthisoption.Bydefault,PuTTYwillnotattempttofindanyauthorisationforyourlocaldisplay.

4.26TheTunnelspanelTheTunnelspanelallowsyoutoconfiguretunnellingofarbitraryconnectiontypesthroughanSSHconnection.

PortforwardingallowsyoutotunnelothertypesofnetworkconnectiondownanSSHsession.Seesection3.5forageneraldiscussionofportforwardingandhowitworks.

TheportforwardingsectionintheTunnelspanelshowsalistofalltheportforwardingsthatPuTTYwilltrytosetupwhenitconnectstotheserver.Bydefaultnoportforwardingsaresetup,sothislistisempty.

Toaddaportforwarding:

Setoneofthe‘Local’or‘Remote’radiobuttons,dependingonwhetheryouwanttoforwardalocalporttoaremotedestination(‘Local’)orforwardaremoteporttoalocaldestination(‘Remote’).Alternatively,select‘Dynamic’ifyouwantPuTTYtoprovidealocalSOCKS4/4A/5proxyonalocalport(notethatthisproxyonlysupportsTCPconnections;theSSHprotocoldoesnotsupportforwardingUDP).Enterasourceportnumberintothe‘Sourceport’box.Forlocalforwardings,PuTTYwilllistenonthisportofyourPC.Forremoteforwardings,yourSSHserverwilllistenonthisportoftheremotemachine.Notethatmostserverswillnotallowyoutolistenonportnumberslessthan1024.Ifyouhaveselected‘Local’or‘Remote’(thisstepisnotneededwith‘Dynamic’),enterahostnameandportnumberseparatedbyacolon,inthe‘Destination’box.Connectionsreceivedonthesourceportwillbedirectedtothisdestination.Forexample,toconnecttoaPOP-3server,youmightenterpopserver.example.com:110.(IfyouneedtoenteraliteralIPv6address,encloseitinsquarebrackets,forinstance‘[::1]:2200’.)Clickthe‘Add’button.Yourforwardingdetailsshouldappearinthelistbox.

Toremoveaportforwarding,simplyselectitsdetailsinthelistbox,and

clickthe‘Remove’button.

Inthe‘Sourceport’box,youcanalsooptionallyenteranIPaddresstolistenon,byspecifying(forinstance)127.0.0.5:79.Seesection3.5formoreinformationonhowthisworksanditsrestrictions.

Inplaceofportnumbers,youcanenterservicenames,iftheyareknowntothelocalsystem.Forinstance,inthe‘Destination’box,youcouldenterpopserver.example.com:pop3.

Youcanmodifythecurrentlyactivesetofportforwardingsinmid-sessionusing‘ChangeSettings’(seesection3.1.3.4).Ifyoudeletealocalordynamicportforwardinginmid-session,PuTTYwillstoplisteningforconnectionsonthatport,soitcanbere-usedbyanotherprogram.Ifyoudeletearemoteportforwarding,notethat:

TheSSH-1protocolcontainsnomechanismforaskingtheservertostoplisteningonaremoteport.TheSSH-2protocoldoescontainsuchamechanism,butnotallSSHserverssupportit.(Inparticular,OpenSSHdoesnotsupportitinanyversionearlierthan3.9.)

IfyouasktodeletearemoteportforwardingandPuTTYcannotmaketheserveractuallystoplisteningontheport,itwillinsteadjuststartrefusingincomingconnectionsonthatport.Therefore,althoughtheportcannotbereusedbyanotherprogram,youcanatleastbereasonablysurethatserver-sideprogramscannolongeraccesstheserviceatyourendoftheportforwarding.

Ifyoudeleteaforwarding,anyexistingconnectionsestablishedusingthatforwardingremainopen.Similarly,changestoglobalsettingssuchas‘Localportsacceptconnectionsfromotherhosts’onlytakeeffectonnewforwardings.

IftheconnectionyouareforwardingoverSSHisitselfasecondSSHconnectionmadebyanothercopyofPuTTY,youmightfindthe‘logicalhostname’configurationoptionusefultowarnPuTTYofwhichhostkeyitshouldbeexpecting.Seesection4.13.5fordetailsofthis.

4.26.1Controllingthevisibilityofforwardedports

4.26.2SelectingInternetprotocolversionforforwardedports

4.26.1ControllingthevisibilityofforwardedportsThesourceportforaforwardedconnectionusuallydoesnotacceptconnectionsfromanymachineexcepttheSSHclientorservermachineitself(forlocalandremoteforwardingsrespectively).TherearecontrolsintheTunnelspaneltochangethis:

The‘Localportsacceptconnectionsfromotherhosts’optionallowsyoutosetuplocal-to-remoteportforwardingsinsuchawaythatmachinesotherthanyourclientPCcanconnecttotheforwardedport.(ThisalsoappliestodynamicSOCKSforwarding.)The‘Remoteportsdothesame’optiondoesthesamethingforremote-to-localportforwardings(sothatmachinesotherthantheSSHservermachinecanconnecttotheforwardedport.)NotethatthisfeatureisonlyavailableintheSSH-2protocol,andnotallSSH-2serverssupportit(OpenSSH3.0doesnot,forexample).

4.26.2SelectingInternetprotocolversionforforwardedportsThisswitchallowsyoutoselectaspecificInternetprotocol(IPv4orIPv6)forthelocalendofaforwardedport.Bydefault,itisseton‘Auto’,whichmeansthat:

foralocal-to-remoteportforwarding,PuTTYwilllistenforincomingconnectionsinbothIPv4and(ifavailable)IPv6foraremote-to-localportforwarding,PuTTYwillchooseasensibleprotocolfortheoutgoingconnection.

ThisoverridesthegeneralInternetprotocolversionpreferenceontheConnectionpanel(seesection4.13.4).

NotethatsomeoperatingsystemsmaylistenforincomingconnectionsinIPv4evenifyouspecificallyaskedforIPv6,becausetheirIPv4andIPv6protocolstacksarelinkedtogether.ApparentlyLinuxdoesthis,andWindowsdoesnot.Soifyou'rerunningPuTTYonWindowsandyoutick‘IPv6’foralocalordynamicportforwarding,itwillonlybeusablebyconnectingtoitusingIPv6;whereasifyoudothesameonLinux,youcanalsouseitwithIPv4.However,ticking‘Auto’shouldalwaysgiveyouaportwhichyoucanconnecttousingeitherprotocol.

4.27TheBugsandMoreBugspanelsNotallSSHserversworkproperly.Variousexistingservershavebugsinthem,whichcanmakeitimpossibleforaclienttotalktothemunlessitknowsaboutthebugandworksaroundit.

SincemostserversannouncetheirsoftwareversionnumberatthebeginningoftheSSHconnection,PuTTYwillattempttodetectwhichbugsitcanexpecttoseeintheserverandautomaticallyenableworkarounds.However,sometimesitwillmakemistakes;iftheserverhasbeendeliberatelyconfiguredtoconcealitsversionnumber,oriftheserverisaversionwhichPuTTY'sbugdatabasedoesnotknowabout,thenPuTTYwillnotknowwhatbugstoexpect.

TheBugsandMoreBugspanels(therearetwobecausewehavesomanybugcompatibilitymodes)allowyoutomanuallyconfigurethebugsPuTTYexpectstoseeintheserver.Eachbugcanbeconfiguredinthreestates:

‘Off’:PuTTYwillassumetheserverdoesnothavethebug.‘On’:PuTTYwillassumetheserverdoeshavethebug.‘Auto’:PuTTYwillusetheserver'sversionnumberannouncementtotrytoguesswhetherornottheserverhasthebug.

4.27.1‘ChokesonSSH-1ignoremessages’4.27.2‘RefusesallSSH-1passwordcamouflage’4.27.3‘ChokesonSSH-1RSAauthentication’4.27.4‘ChokesonSSH-2ignoremessages’4.27.5‘ChokesonPuTTY'sSSH-2‘winadj’requests’4.27.6‘MiscomputesSSH-2HMACkeys’4.27.7‘MiscomputesSSH-2encryptionkeys’4.27.8‘RequirespaddingonSSH-2RSAsignatures’4.27.9‘MisusesthesessionIDinSSH-2PKauth’4.27.10‘HandlesSSH-2keyre-exchangebadly’4.27.11‘IgnoresSSH-2maximumpacketsize’4.27.12‘Repliestorequestsonclosedchannels’4.27.13‘Onlysupportspre-RFC4419SSH-2DHGEX’

4.27.1‘ChokesonSSH-1ignoremessages’Anignoremessage(SSH_MSG_IGNORE)isamessageintheSSHprotocolwhichcanbesentfromtheclienttotheserver,orfromtheservertotheclient,atanytime.Eithersideisrequiredtoignorethemessagewheneveritreceivesit.PuTTYusesignoremessagestohidethepasswordpacketinSSH-1,sothatalistenercannottellthelengthoftheuser'spassword;italsousesignoremessagesforconnectionkeepalives(seesection4.13.1).

Ifthisbugisdetected,PuTTYwillstopusingignoremessages.Thismeansthatkeepaliveswillstopworking,andPuTTYwillhavetofallbacktoasecondarydefenceagainstSSH-1password-lengtheavesdropping.Seesection4.27.2.Ifthisbugisenabledwhentalkingtoacorrectserver,thesessionwillsucceed,butkeepaliveswillnotworkandthesessionmightbemorevulnerabletoeavesdroppersthanitcouldbe.

4.27.2‘RefusesallSSH-1passwordcamouflage’WhentalkingtoanSSH-1serverwhichcannotdealwithignoremessages(seesection4.27.1),PuTTYwillattempttodisguisethelengthoftheuser'spasswordbysendingadditionalpaddingwithinthepasswordpacket.ThisistechnicallyaviolationoftheSSH-1specification,andsoPuTTYwillonlydoitwhenitcannotusestandards-compliantignoremessagesascamouflage.Inthissense,foraservertorefusetoacceptapaddedpasswordpacketisnotreallyabug,butitdoesmakelifeinconvenientiftheservercanalsonothandleignoremessages.

Ifthis‘bug’isdetected,PuTTYwillassumethatneitherignoremessagesnorpaddingareacceptable,andthatitthushasnochoicebuttosendtheuser'spasswordwithnoformofcamouflage,sothataneavesdroppinguserwillbeeasilyabletofindouttheexactlengthofthepassword.Ifthisbugisenabledwhentalkingtoacorrectserver,thesessionwillsucceed,butwillbemorevulnerabletoeavesdroppersthanitcouldbe.

ThisisanSSH-1-specificbug.SSH-2issecureagainstthistypeofattack.

4.27.3‘ChokesonSSH-1RSAauthentication’SomeSSH-1serverscannotdealwithRSAauthenticationmessagesatall.IfPageantisrunningandcontainsanySSH-1keys,PuTTYwillnormallyautomaticallytryRSAauthenticationbeforefallingbacktopasswords,sotheseserverswillcrashwhentheyseetheRSAattempt.

Ifthisbugisdetected,PuTTYwillgostraighttopasswordauthentication.Ifthisbugisenabledwhentalkingtoacorrectserver,thesessionwillsucceed,butofcourseRSAauthenticationwillbeimpossible.

ThisisanSSH-1-specificbug.

4.27.4‘ChokesonSSH-2ignoremessages’Anignoremessage(SSH_MSG_IGNORE)isamessageintheSSHprotocolwhichcanbesentfromtheclienttotheserver,orfromtheservertotheclient,atanytime.Eithersideisrequiredtoignorethemessagewheneveritreceivesit.PuTTYusesignoremessagesinSSH-2toconfusetheencrypteddatastreamandmakeithardertocryptanalyse.Italsousesignoremessagesforconnectionkeepalives(seesection4.13.1).

Ifitbelievestheservertohavethisbug,PuTTYwillstopusingignoremessages.Ifthisbugisenabledwhentalkingtoacorrectserver,thesessionwillsucceed,butkeepaliveswillnotworkandthesessionmightbelesscryptographicallysecurethanitcouldbe.

4.27.5‘ChokesonPuTTY'sSSH-2‘winadj’requests’PuTTYsometimessendsaspecialrequesttoSSHserversinthemiddleofchanneldata,withthenamewinadj@putty.projects.tartarus.org(seesectionF.1).Thepurposeofthisrequestistomeasuretheround-triptimetotheserver,whichPuTTYusestotuneitsflowcontrol.Theserverdoesnotactuallyhavetounderstandthemessage;itisexpectedtosendbackaSSH_MSG_CHANNEL_FAILUREmessageindicatingthatitdidn'tunderstandit.(AllPuTTYneedsforitstimingcalculationsissomekindofresponse.)

IthasbeenknownforsomeSSHserverstogetconfusedbythismessageinonewayoranother–becauseithasalongname,orbecausetheycan'tcopewithunrecognisedrequestnameseventotheextentofsendingbackthecorrectfailureresponse,orbecausetheyhandleitsensiblybutfilluptheserver'slogfilewithpointlessspam,orwhatever.PuTTYthereforesupportsthisbug-compatibilityflag:ifitbelievestheserverhasthisbug,itwillneversendits‘winadj@putty.projects.tartarus.org’request,andwillmakedowithoutitstimingdata.

4.27.6‘MiscomputesSSH-2HMACkeys’Versions2.3.0andbelowoftheSSHserversoftwarefromssh.comcomputethekeysfortheirHMACmessageauthenticationcodesincorrectly.AtypicalsymptomofthisproblemisthatPuTTYdiesunexpectedlyatthebeginningofthesession,saying‘IncorrectMACreceivedonpacket’.

Ifthisbugisdetected,PuTTYwillcomputeitsHMACkeysinthesamewayasthebuggyserver,sothatcommunicationwillstillbepossible.Ifthisbugisenabledwhentalkingtoacorrectserver,communicationwillfail.

ThisisanSSH-2-specificbug.

4.27.7‘MiscomputesSSH-2encryptionkeys’Versionsbelow2.0.11oftheSSHserversoftwarefromssh.comcomputethekeysforthesessionencryptionincorrectly.Thisproblemcancausevariouserrormessages,suchas‘Incomingpacketwasgarbledondecryption’,orpossiblyeven‘Outofmemory’.

Ifthisbugisdetected,PuTTYwillcomputeitsencryptionkeysinthesamewayasthebuggyserver,sothatcommunicationwillstillbepossible.Ifthisbugisenabledwhentalkingtoacorrectserver,communicationwillfail.

ThisisanSSH-2-specificbug.

4.27.8‘RequirespaddingonSSH-2RSAsignatures’Versionsbelow3.3ofOpenSSHrequireSSH-2RSAsignaturestobepaddedwithzerobytestothesamelengthastheRSAkeymodulus.TheSSH-2specificationsaysthatanunpaddedsignatureMUSTbeaccepted,sothisisabug.AtypicalsymptomofthisproblemisthatPuTTYmysteriouslyfailsRSAauthenticationonceineveryfewhundredattempts,andfallsbacktopasswords.

Ifthisbugisdetected,PuTTYwillpaditssignaturesinthewayOpenSSHexpects.Ifthisbugisenabledwhentalkingtoacorrectserver,itislikelythatnodamagewillbedone,sincecorrectserversusuallystillacceptpaddedsignaturesbecausethey'reusedtotalkingtoOpenSSH.

ThisisanSSH-2-specificbug.

4.27.9‘MisusesthesessionIDinSSH-2PKauth’Versionsbelow2.3ofOpenSSHrequireSSH-2public-keyauthenticationtobedoneslightlydifferently:thedatatobesignedbytheclientcontainsthesessionIDformattedinadifferentway.Ifpublic-keyauthenticationmysteriouslydoesnotworkbuttheEventLog(seesection3.1.3.1)thinksithassuccessfullysentasignature,itmightbeworthenablingtheworkaroundforthisbugtoseeifithelps.

Ifthisbugisdetected,PuTTYwillsigndatainthewayOpenSSHexpects.Ifthisbugisenabledwhentalkingtoacorrectserver,SSH-2public-keyauthenticationwillfail.

ThisisanSSH-2-specificbug.

4.27.10‘HandlesSSH-2keyre-exchangebadly’SomeSSHserverscannotcopewithrepeatkeyexchangeatall,andwillignoreattemptsbytheclienttostartone.SincePuTTYpausesthesessionwhileperformingarepeatkeyexchange,theeffectofthiswouldbetocausethesessiontohangafteranhour(unlessyouhaveyourrekeytimeoutsetdifferently;seesection4.19.2formoreaboutrekeys).Other,veryold,SSHservershandlerepeatkeyexchangeevenmorebadly,anddisconnectuponreceivingarepeatkeyexchangerequest.

Ifthisbugisdetected,PuTTYwillneverinitiatearepeatkeyexchange.Ifthisbugisenabledwhentalkingtoacorrectserver,thesessionshouldstillfunction,butmaybelesssecurethanyouwouldexpect.

ThisisanSSH-2-specificbug.

4.27.11‘IgnoresSSH-2maximumpacketsize’WhenanSSH-2channelissetup,eachendannouncesthemaximumsizeofdatapacketthatitiswillingtoreceiveforthatchannel.SomeserversignorePuTTY'sannouncementandsendpacketslargerthanPuTTYiswillingtoaccept,causingittoreport‘Incomingpacketwasgarbledondecryption’.

Ifthisbugisdetected,PuTTYneverallowsthechannel'sflow-controlwindowtogrowlargeenoughtoallowtheservertosendanover-sizedpacket.Ifthisbugisenabledwhentalkingtoacorrectserver,thesessionwillworkcorrectly,butdownloadperformancewillbelessthanitcouldbe.

4.27.12‘Repliestorequestsonclosedchannels’TheSSHprotocolaspublishedinRFC4254hasanambiguitywhicharisesifonesideofaconnectiontriestocloseachannel,whiletheothersidesimultaneouslysendsarequestwithinthechannelandasksforareply.RFC4254leavesitunclearwhethertheclosingsideshouldreplytothechannelrequestafterhavingannounceditsintentiontoclosethechannel.

Discussionontheietf-sshmailinglistinApril2014formedaclearconsensusthattherightanswerisno.However,becauseoftheambiguityinthespecification,someSSHservershaveimplementedtheotherpolicy;forexample,OpenSSHusedtountilitwasfixed.

BecausePuTTYsendschannelrequestswiththe‘wantreply’flagthroughoutchannels'lifetime(seesection4.27.5),it'spossiblethatwhenconnectingtosuchaserveritmightreceiveareplytoarequestafteritthinksthechannelhasentirelyclosed,andterminatewithanerroralongthelinesof‘ReceivedSSH2_MSG_CHANNEL_FAILUREfornonexistentchannel256’.

4.27.13‘Onlysupportspre-RFC4419SSH-2DHGEX’TheSSHkeyexchangemethodthatusesDiffie-Hellmangroupexchangewasredesignedafteritsoriginalrelease,touseaslightlymoresophisticatedsetupmessage.AlmostallSSHimplementationsswitchedovertothenewversion.(PuTTYwasoneofthelast.)Afewoldserversstillonlysupporttheoldone.

Ifthisbugisdetected,andtheclientandservernegotiateDiffie-Hellmangroupexchange,thenPuTTYwillsendtheoldmessagenowknownasSSH2_MSG_KEX_DH_GEX_REQUEST_OLDinplaceofthenewSSH2_MSG_KEX_DH_GEX_REQUEST.

ThisisanSSH-2-specificbug.

4.28TheSerialpanelTheSerialpanelallowsyoutoconfigureoptionsthatonlyapplywhenPuTTYisconnectingtoalocalserialline.

4.28.1Selectingaseriallinetoconnectto4.28.2Selectingthespeedofyourserialline4.28.3Selectingthenumberofdatabits4.28.4Selectingthenumberofstopbits4.28.5Selectingtheserialparitycheckingscheme4.28.6Selectingtheserialflowcontrolscheme

4.28.1SelectingaseriallinetoconnecttoThe‘Seriallinetoconnectto’boxallowsyoutochoosewhichseriallineyouwantPuTTYtotalkto,ifyourcomputerhasmorethanoneserialport.

OnWindows,thefirstseriallineiscalledCOM1,andifthereisaseconditiscalledCOM2,andsoon.

ThisconfigurationsettingisalsovisibleontheSessionpanel,whereitreplacesthe‘HostName’box(seesection4.1.1)iftheconnectiontypeissetto‘Serial’.

4.28.2SelectingthespeedofyourseriallineThe‘Speed’boxallowsyoutochoosethespeed(or‘baudrate’)atwhichtotalktotheserialline.Typicalvaluesmightbe9600,19200,38400or57600.Whichoneyouneedwilldependonthedeviceattheotherendoftheserialcable;consultthemanualforthatdeviceifyouareindoubt.

ThisconfigurationsettingisalsovisibleontheSessionpanel,whereitreplacesthe‘Port’box(seesection4.1.1)iftheconnectiontypeissetto‘Serial’.

4.28.3SelectingthenumberofdatabitsThe‘Databits’boxallowsyoutochoosehowmanydatabitsaretransmittedineachbytesentorreceivedthroughtheserialline.Typicalvaluesare7or8.

4.28.4SelectingthenumberofstopbitsThe‘Stopbits’boxallowsyoutochoosehowmanystopbitsareusedintheseriallineprotocol.Typicalvaluesare1,1.5or2.

4.28.5SelectingtheserialparitycheckingschemeThe‘Parity’boxallowsyoutochoosewhattypeofparitycheckingisusedontheserialline.Thesettingsare:

‘None’:noparitybitissentatall.‘Odd’:anextraparitybitissentalongsideeachbyte,andarrangedsothatthetotalnumberof1bitsisodd.‘Even’:anextraparitybitissentalongsideeachbyte,andarrangedsothatthetotalnumberof1bitsiseven.‘Mark’:anextraparitybitissentalongsideeachbyte,andalwayssetto1.‘Space’:anextraparitybitissentalongsideeachbyte,andalwayssetto0.

4.28.6SelectingtheserialflowcontrolschemeThe‘Flowcontrol’boxallowsyoutochoosewhattypeofflowcontrolcheckingisusedontheserialline.Thesettingsare:

‘None’:noflowcontrolisdone.Datamaybelostifeithersideattemptstosendfasterthantheseriallinepermits.‘XON/XOFF’:flowcontrolisdonebysendingXONandXOFFcharacterswithinthedatastream.‘RTS/CTS’:flowcontrolisdoneusingtheRTSandCTSwiresontheserialline.‘DSR/DTR’:flowcontrolisdoneusingtheDSRandDTRwiresontheserialline.

4.29StoringconfigurationinafilePuTTYdoesnotcurrentlysupportstoringitsconfigurationinafileinsteadoftheRegistry.However,youcanworkaroundthiswithacoupleofbatchfiles.

Youwillneedafilecalled(say)PUTTY.BATwhichimportsthecontentsofafileintotheRegistry,thenrunsPuTTY,exportsthecontentsoftheRegistrybackintothefile,anddeletestheRegistryentries.ThiscanallbedoneusingtheRegeditcommandlineoptions,soit'sallautomatic.HereiswhatyouneedinPUTTY.BAT:

@ECHOOFF

regedit/sputty.reg

regedit/sputtyrnd.reg

start/wputty.exe

regedit/eanew.regHKEY_CURRENT_USER\Software\SimonTatham\PuTTY

copynew.regputty.reg

delnew.reg

regedit/sputtydel.reg

Thisbatchfileneedstwoauxiliaryfiles:PUTTYRND.REGwhichsetsupaninitialsafelocationforthePUTTY.RNDrandomseedfile,andPUTTYDEL.REGwhichdestroyseverythingintheRegistryonceit'sbeensuccessfullysavedbacktothefile.

HereisPUTTYDEL.REG:

REGEDIT4

[-HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]

HereisanexamplePUTTYRND.REGfile:

REGEDIT4

[HKEY_CURRENT_USER\Software\SimonTatham\PuTTY]

"RandSeedFile"="a:\\putty.rnd"

Youshouldreplacea:\putty.rndwiththelocationwhereyouwanttostoreyourrandomnumberdata.IftheaimistocarryaroundPuTTYanditssettingsononeUSBstick,youprobablywanttostoreitontheUSB

stick.

Chapter5:UsingPSCPtotransferfilessecurelyPSCP,thePuTTYSecureCopyclient,isatoolfortransferringfilessecurelybetweencomputersusinganSSHconnection.

IfyouhaveanSSH-2server,youmightpreferPSFTP(seechapter6)forinteractiveuse.PSFTPdoesnotingeneralworkwithSSH-1servers,however.

5.1StartingPSCP5.2PSCPUsage

5.2.1Thebasics5.2.2Options5.2.3Returnvalue5.2.4UsingpublickeyauthenticationwithPSCP

5.1StartingPSCPPSCPisacommandlineapplication.Thismeansthatyoucannotjustdouble-clickonitsicontorunitandinsteadyouhavetobringupaconsolewindow.WithWindows95,98,andME,thisiscalledan‘MS-DOSPrompt’andwithWindowsNT,2000,andXP,itiscalleda‘CommandPrompt’.ItshouldbeavailablefromtheProgramssectionofyourStartMenu.

TostartPSCPitwillneedeithertobeonyourPATHorinyourcurrentdirectory.ToaddthedirectorycontainingPSCPtoyourPATHenvironmentvariable,typeintotheconsolewindow:

setPATH=C:\path\to\putty\directory;%PATH%

Thiswillonlyworkforthelifetimeofthatparticularconsolewindow.TosetyourPATHmorepermanentlyonWindowsNT,2000,andXP,usetheEnvironmenttaboftheSystemControlPanel.OnWindows95,98,andME,youwillneedtoedityourAUTOEXEC.BATtoincludeasetcommandliketheoneabove.

5.2PSCPUsageOnceyou'vegotaconsolewindowtotypeinto,youcanjusttypepscponitsowntobringupausagemessage.ThistellsyoutheversionofPSCPyou'reusing,andgivesyouabriefsummaryofhowtousePSCP:

Z:\owendadmin>pscp

PuTTYSecureCopyclient

Release0.70

Usage:pscp[options][user@]host:sourcetarget

pscp[options]source[source...][user@]host:target

pscp[options]-ls[user@]host:filespec

Options:

-Vprintversioninformationandexit

-pgpfpprintPGPkeyfingerprintsandexit

-ppreservefileattributes

-qquiet,don'tshowstatistics

-rcopydirectoriesrecursively

-vshowverbosemessages

-loadsessnameLoadsettingsfromsavedsession

-Pportconnecttospecifiedport

-luserconnectwithspecifiedusername

-pwpasswloginwithspecifiedpassword

-1-2forceuseofparticularSSHprotocolversion

-4-6forceuseofIPv4orIPv6

-Cenablecompression

-ikeyprivatekeyfileforuserauthentication

-noagentdisableuseofPageant

-agentenableuseofPageant

-hostkeyaa:bb:cc:...

manuallyspecifyahostkey(mayberepeated)

-batchdisableallinteractiveprompts

-proxycmdcommand

use'command'aslocalproxy

-unsafeallowserver-sidewildcards(DANGEROUS)

-sftpforceuseofSFTPprotocol

-scpforceuseofSCPprotocol

-sshlogfile

-sshrawlogfile

logprotocoldetailstoafile

(PSCP'sinterfaceismuchliketheUnixscpcommand,ifyou'refamiliarwiththat.)

5.2.1Thebasics

5.2.1.1user5.2.1.2host5.2.1.3source5.2.1.4target

5.2.2Options5.2.2.1-lslistremotefiles5.2.2.2-ppreservefileattributes5.2.2.3-qquiet,don'tshowstatistics5.2.2.4-rcopiesdirectoriesrecursively5.2.2.5-batchavoidinteractiveprompts5.2.2.6-sftp,-scpforceuseofparticularprotocol

5.2.3Returnvalue5.2.4UsingpublickeyauthenticationwithPSCP

5.2.1ThebasicsToreceive(a)file(s)fromaremoteserver:

pscp[options][user@]host:sourcetarget

Sotocopythefile/etc/hostsfromtheserverexample.comasuserfredtothefilec:\temp\example-hosts.txt,youwouldtype:

pscpfred@example.com:/etc/hostsc:\temp\example-hosts.txt

Tosend(a)file(s)toaremoteserver:

pscp[options]source[source...][user@]host:target

Sotocopythelocalfilec:\documents\foo.txttotheserverexample.comasuserfredtothefile/tmp/fooyouwouldtype:

pscpc:\documents\foo.txtfred@example.com:/tmp/foo

Youcanusewildcardstotransfermultiplefilesineitherdirection,likethis:

pscpc:\documents\*.docfred@example.com:docfiles

pscpfred@example.com:source/*.cc:\source

However,inthesecondcase(usingawildcardformultipleremotefiles)youmayseeawarningsayingsomethinglike‘warning:remotehosttriedtowritetoafilecalled‘terminal.c’whenwerequestedafilecalled‘*.c’.Ifthisisawildcard,considerupgradingtoSSH-2orusingthe‘-unsafe’option.Renamingofthisfilehasbeendisallowed’.

Thisisduetoafundamentalinsecurityintheold-styleSCPprotocol:theclientsendsthewildcardstring(*.c)totheserver,andtheserversendsbackasequenceoffilenamesthatmatchthewildcardpattern.However,thereisnothingtostoptheserversendingbackadifferentpatternandwritingoveroneofyourotherfiles:ifyourequest*.c,theservermightsendbackthefilenameAUTOEXEC.BATandinstallavirusforyou.Sincethewildcardmatchingrulesaredecidedbytheserver,theclientcannotreliablyverifythatthefilenamessentbackmatchthepattern.

PSCPwillattempttousethenewerSFTPprotocol(partofSSH-2)wherepossible,whichdoesnotsufferfromthissecurityflaw.IfyouaretalkingtoanSSH-2serverwhichsupportsSFTP,youwillneverseethiswarning.(YoucanforceuseoftheSFTPprotocol,ifavailable,with-sftp-seesection5.2.2.6.)

Ifyoureallyneedtouseaserver-sidewildcardwithanSSH-1server,youcanusethe-unsafecommandlineoptionwithPSCP:

pscp-unsafefred@example.com:source/*.cc:\source

Thiswillsuppressthewarningmessageandthefiletransferwillhappen.However,youshouldbeawarethatbyusingthisoptionyouaregivingtheservertheabilitytowritetoanyfileinthetargetdirectory,soyoushouldonlyusethisoptionifyoutrusttheserveradministratornottobemalicious(andnottolettheservermachinebecrackedbymaliciouspeople).Alternatively,doanysuchdownloadinanewlycreatedemptydirectory.(Evenin‘unsafe’mode,PSCPwillstillprotectyouagainsttheservertryingtogetoutofthatdirectoryusingpathnamesincluding‘..’.)

5.2.1.1user5.2.1.2host5.2.1.3source5.2.1.4target

5.2.1.1userTheloginnameontheremoteserver.Ifthisisomitted,andhostisaPuTTYsavedsession,PSCPwilluseanyusernamespecifiedbythatsavedsession.Otherwise,PSCPwillattempttousethelocalWindowsusername.

5.2.1.2hostThenameoftheremoteserver,orthenameofanexistingPuTTYsavedsession.Inthelattercase,thesession'ssettingsforhostname,portnumber,ciphertypeandusernamewillbeused.

5.2.1.3sourceOneormoresourcefiles.Wildcardsareallowed.Thesyntaxofwildcardsdependsonthesystemtowhichtheyapply,soifyouarecopyingfromaWindowssystemtoaUNIXsystem,youshoulduseWindowswildcardsyntax(e.g.*.*),butifyouarecopyingfromaUNIXsystemtoaWindowssystem,youwouldusethewildcardsyntaxallowedbyyourUNIXshell(e.g.*).

Ifthesourceisaremoteserverandyoudonotspecifyafullpathname(inUNIX,apathnamebeginningwitha/(slash)character),whatyouspecifyasasourcewillbeinterpretedrelativetoyourhomedirectoryontheremoteserver.

5.2.1.4targetThefilenameordirectorytoputthefile(s).Whencopyingfromaremoteservertoalocalhost,youmaywishsimplytoplacethefile(s)inthecurrentdirectory.Todothis,youshouldspecifyatargetof..Forexample:

pscpfred@example.com:/home/tom/.emacs.

...wouldcopy/home/tom/.emacsontheremoteservertothecurrentdirectory.

Aswiththesourceparameter,ifthetargetisonaremoteserverandisnotafullpathname,itisinterpretedrelativetoyourhomedirectoryontheremoteserver.

5.2.2OptionsPSCPacceptsallthegeneralcommandlineoptionssupportedbythePuTTYtools,excepttheoneswhichmakenosenseinafiletransferutility.Seesection3.8.3foradescriptionoftheseoptions.(TheonesnotsupportedbyPSCPareclearlymarked.)

PSCPalsosupportssomeofitsownoptions.ThefollowingsectionsdescribePSCP'sspecificcommand-lineoptions.

5.2.2.1-lslistremotefiles5.2.2.2-ppreservefileattributes5.2.2.3-qquiet,don'tshowstatistics5.2.2.4-rcopiesdirectoriesrecursively5.2.2.5-batchavoidinteractiveprompts5.2.2.6-sftp,-scpforceuseofparticularprotocol

5.2.2.1-lslistremotefilesIfthe-lsoptionisgiven,nofilesaretransferred;instead,remotefilesarelisted.Onlyahostnamespecificationandoptionalremotefilespecificationneedbegiven.Forexample:

pscp-lsfred@example.com:dir1

TheSCPprotocoldoesnotcontainwithinitselfameansoflistingfiles.IfSCPisinuse,thisoptionthereforeassumesthattheserverrespondsappropriatelytothecommandls-la;thismaynotworkwithallservers.

IfSFTPisinuse,thisoptionshouldworkwithallservers.

5.2.2.2-ppreservefileattributesBydefault,filescopiedwithPSCParetimestampedwiththedateandtimetheywerecopied.The-poptionpreservestheoriginaltimestamponcopiedfiles.

5.2.2.3-qquiet,don'tshowstatisticsBydefault,PSCPdisplaysameterdisplayingtheprogressofthecurrenttransfer:

mibs.tar|168kB|84.0kB/s|ETA:00:00:13|13%

Thefieldsinthisdisplayare(fromlefttoright),filename,size(inkilobytes)offiletransferredsofar,estimateofhowfastthefileisbeingtransferred(inkilobytespersecond),estimatedtimethatthetransferwillbecomplete,andpercentageofthefilesofartransferred.The-qoptiontoPSCPsuppressestheprintingofthesestatistics.

5.2.2.4-rcopiesdirectoriesrecursivelyBydefault,PSCPwillonlycopyfiles.Anydirectoriesyouspecifytocopywillbeskipped,aswilltheircontents.The-roptiontellsPSCPtodescendintoanydirectoriesyouspecify,andtocopythemandtheircontents.ThisallowsyoutousePSCPtotransferwholedirectorystructuresbetweenmachines.

5.2.2.5-batchavoidinteractivepromptsIfyouusethe-batchoption,PSCPwillnevergiveaninteractivepromptwhileestablishingtheconnection.Iftheserver'shostkeyisinvalid,forexample(seesection2.2),thentheconnectionwillsimplybeabandonedinsteadofaskingyouwhattodonext.

ThismayhelpPSCP'sbehaviourwhenitisusedinautomatedscripts:using-batch,ifsomethinggoeswrongatconnectiontime,thebatchjobwillfailratherthanhang.

5.2.2.6-sftp,-scpforceuseofparticularprotocolAsmentionedinsection5.2.1,therearetwodifferentfiletransferprotocolsinusewithSSH.Despiteitsname,PSCP(likemanyotherostensiblescpclients)canuseeitheroftheseprotocols.

TheolderSCPprotocoldoesnothaveawrittenspecificationandleavesalotofdetailtotheserverplatform.Wildcardsareexpandedontheserver.Thesimpledesignmeansthatanywildcardspecificationsupportedbytheserverplatform(suchasbraceexpansion)canbeused,butalsoleadstointeroperabilityissuessuchaswithfilenamequoting(forinstance,wherefilenamescontainspaces),andalsothesecurityissuedescribedinsection5.2.1.

ThenewerSFTPprotocol,whichisusuallyassociatedwithSSH-2servers,isspecifiedinamoreplatformindependentway,andleavesissuessuchaswildcardsyntaxuptotheclient.(PuTTY'sSFTPwildcardsyntaxisdescribedinsection6.2.2.)Thismakesitmoreconsistentacrossplatforms,moresuitableforscriptingandautomation,andavoidssecurityissueswithwildcardmatching.

NormallyPSCPwillattempttousetheSFTPprotocol,andonlyfallbacktotheSCPprotocolifSFTPisnotavailableontheserver.

The-scpoptionforcesPSCPtousetheSCPprotocolorquit.

The-sftpoptionforcesPSCPtousetheSFTPprotocolorquit.Whenthisoptionisspecified,PSCPlooksharderforanSFTPserver,whichmayallowuseofSFTPwithSSH-1dependingonserversetup.

5.2.3ReturnvaluePSCPreturnsanERRORLEVELofzero(success)onlyifthefileswerecorrectlytransferred.Youcantestforthisinabatchfile,usingcodesuchasthis:

pscpfile*.*user@hostname:

iferrorlevel1echoTherewasanerror

5.2.4UsingpublickeyauthenticationwithPSCPLikePuTTY,PSCPcanauthenticateusingapublickeyinsteadofapassword.Therearethreewaysyoucandothis.

Firstly,PSCPcanusePuTTYsavedsessionsinplaceofhostnames(seesection5.2.1.2).Soyouwoulddothis:

RunPuTTY,andcreateaPuTTYsavedsession(seesection4.1.2)whichspecifiesyourprivatekeyfile(seesection4.22.8).Youwillprobablyalsowanttospecifyausernametologinas(seesection4.14.1).InPSCP,youcannowusethenameofthesessioninsteadofahostname:typepscpsessionname:filelocalfile,wheresessionnameisreplacedbythenameofyoursavedsession.

Secondly,youcansupplythenameofaprivatekeyfileonthecommandline,withthe-ioption.Seesection3.8.3.18formoreinformation.

Thirdly,PSCPwillattempttoauthenticateusingPageantifPageantisrunning(seechapter9).Soyouwoulddothis:

EnsurePageantisrunning,andhasyourprivatekeystoredinit.SpecifyauserandhostnametoPSCPasnormal.PSCPwillautomaticallydetectPageantandtrytousethekeyswithinit.

Formoregeneralinformationonpublic-keyauthentication,seechapter8.

Chapter6:UsingPSFTPtotransferfilessecurelyPSFTP,thePuTTYSFTPclient,isatoolfortransferringfilessecurelybetweencomputersusinganSSHconnection.

PSFTPdiffersfromPSCPinthefollowingways:

PSCPshouldworkonvirtuallyeverySSHserver.PSFTPusesthenewSFTPprotocol,whichisafeatureofSSH-2only.(PSCPwillalsousethisprotocolifitcan,butthereisanSSH-1equivalentitcanfallbacktoifitcannot.)PSFTPallowsyoutorunaninteractivefiletransfersession,muchliketheWindowsftpprogram.Youcanlistthecontentsofdirectories,browsearoundthefilesystem,issuemultiplegetandputcommands,andeventuallylogout.Bycontrast,PSCPisdesignedtodoasinglefiletransferoperationandimmediatelyterminate.

6.1StartingPSFTP6.1.1-b:specifyafilecontainingbatchcommands6.1.2-bc:displaybatchcommandsastheyarerun6.1.3-be:continuebatchprocessingonerrors6.1.4-batch:avoidinteractiveprompts

6.2RunningPSFTP6.2.1GeneralquotingrulesforPSFTPcommands6.2.2WildcardsinPSFTP6.2.3Theopencommand:startasession6.2.4Thequitcommand:endyoursession6.2.5Theclosecommand:closeyourconnection6.2.6Thehelpcommand:getquickonlinehelp6.2.7Thecdandpwdcommands:changingtheremoteworkingdirectory6.2.8Thelcdandlpwdcommands:changingthelocalworkingdirectory6.2.9Thegetcommand:fetchafilefromtheserver6.2.10Theputcommand:sendafiletotheserver6.2.11Themgetandmputcommands:fetchorsendmultiplefiles

6.2.12Theregetandreputcommands:resumingfiletransfers6.2.13Thedircommand:listremotefiles6.2.14Thechmodcommand:changepermissionsonremotefiles6.2.15Thedelcommand:deleteremotefiles6.2.16Themkdircommand:createremotedirectories6.2.17Thermdircommand:removeremotedirectories6.2.18Themvcommand:moveandrenameremotefiles6.2.19The!command:runalocalWindowscommand

6.3UsingpublickeyauthenticationwithPSFTP

6.1StartingPSFTPTheusualwaytostartPSFTPisfromacommandprompt,muchlikePSCP.Todothis,itwillneedeithertobeonyourPATHorinyourcurrentdirectory.ToaddthedirectorycontainingPSFTPtoyourPATHenvironmentvariable,typeintotheconsolewindow:

setPATH=C:\path\to\putty\directory;%PATH%

UnlikePSCP,however,PSFTPhasnocomplexcommand-linesyntax;youjustspecifyahostnameandperhapsausername:

psftpserver.example.com

orperhaps

psftpfred@server.example.com

Alternatively,ifyoujusttypepsftponitsown(ordouble-clickthePSFTPiconintheWindowsGUI),youwillseethePSFTPprompt,andamessagetellingyouPSFTPhasnotconnectedtoanyserver:

C:\>psftp

psftp:nohostnamespecified;use"openhost.name"toconnect

psftp>

Atthispointyoucantypeopenserver.example.comoropenfred@server.example.comtostartasession.

PSFTPacceptsallthegeneralcommandlineoptionssupportedbythePuTTYtools,excepttheoneswhichmakenosenseinafiletransferutility.Seesection3.8.3foradescriptionoftheseoptions.(TheonesnotsupportedbyPSFTPareclearlymarked.)

PSFTPalsosupportssomeofitsownoptions.ThefollowingsectionsdescribePSFTP'sspecificcommand-lineoptions.

6.1.1-b:specifyafilecontainingbatchcommands6.1.2-bc:displaybatchcommandsastheyarerun6.1.3-be:continuebatchprocessingonerrors

6.1.4-batch:avoidinteractiveprompts

6.1.1-b:specifyafilecontainingbatchcommandsInnormaloperation,PSFTPisaninteractiveprogramwhichdisplaysacommandlineandacceptscommandsfromthekeyboard.

IfyouneedtodoautomatedtaskswithPSFTP,youwouldprobablyprefertospecifyasetofcommandsinadvanceandhavethemexecutedautomatically.The-boptionallowsyoutodothis.Youuseitwithafilenamecontainingbatchcommands.Forexample,youmightcreateafilecalledmyscript.scrcontaininglineslikethis:

cd/home/ftp/users/jeff

deljam-old.tar.gz

renjam.tar.gzjam-old.tar.gz

putjam.tar.gz

chmoda+rjam.tar.gz

andthenyoucouldrunthescriptbytyping

psftpuser@hostname-bmyscript.scr

Whenyourunabatchscriptinthisway,PSFTPwillabortthescriptifanycommandfailstocompletesuccessfully.Tochangethisbehaviour,youcanaddthe-beoption(section6.1.3).

PSFTPwillterminateafteritfinishesexecutingthebatchscript.

6.1.2-bc:displaybatchcommandsastheyarerunThe-bcoptionalterswhatPSFTPdisplayswhileprocessingabatchscriptspecifiedwith-b.Withthe-bcoption,PSFTPwilldisplaypromptsandcommandsjustasifthecommandshadbeentypedatthekeyboard.Soinsteadofseeingthis:

C:\>psftpfred@hostname-bbatchfile

Sentusername"fred"

Remoteworkingdirectoryis/home/fred

Listingdirectory/home/fred/lib

drwxrwsr-x4fredfred1024Sep610:42.

drwxr-sr-x25fredfred2048Dec1409:36..

drwxrwsr-x3fredfred1024Apr172000jed

lrwxrwxrwx1fredfred24Apr172000timber

drwxrwsr-x2fredfred1024Mar132000trn

youmightseethis:

C:\>psftpfred@hostname-bc-bbatchfile

Sentusername"fred"

Remoteworkingdirectoryis/home/fred

psftp>dirlib

Listingdirectory/home/fred/lib

drwxrwsr-x4fredfred1024Sep610:42.

drwxr-sr-x25fredfred2048Dec1409:36..

drwxrwsr-x3fredfred1024Apr172000jed

lrwxrwxrwx1fredfred24Apr172000timber

drwxrwsr-x2fredfred1024Mar132000trn

psftp>quit

6.1.3-be:continuebatchprocessingonerrorsWhenrunningabatchfile,thisadditionaloptioncausesPSFTPtocontinueprocessingevenifacommandfailstocompletesuccessfully.

Youmightwantthistohappenifyouwantedtodeleteafileanddidn'tcareifitwasalreadynotpresent,forexample.

6.1.4-batch:avoidinteractivepromptsIfyouusethe-batchoption,PSFTPwillnevergiveaninteractivepromptwhileestablishingtheconnection.Iftheserver'shostkeyisinvalid,forexample(seesection2.2),thentheconnectionwillsimplybeabandonedinsteadofaskingyouwhattodonext.

ThismayhelpPSFTP'sbehaviourwhenitisusedinautomatedscripts:using-batch,ifsomethinggoeswrongatconnectiontime,thebatchjobwillfailratherthanhang.

6.2RunningPSFTPOnceyouhavestartedyourPSFTPsession,youwillseeapsftp>prompt.Youcannowtypecommandstoperformfile-transferfunctions.Thissectionlistsalltheavailablecommands.

Anylinestartingwitha#willbetreatedasacommentandignored.

6.2.1GeneralquotingrulesforPSFTPcommands6.2.2WildcardsinPSFTP6.2.3Theopencommand:startasession6.2.4Thequitcommand:endyoursession6.2.5Theclosecommand:closeyourconnection6.2.6Thehelpcommand:getquickonlinehelp6.2.7Thecdandpwdcommands:changingtheremoteworkingdirectory6.2.8Thelcdandlpwdcommands:changingthelocalworkingdirectory6.2.9Thegetcommand:fetchafilefromtheserver6.2.10Theputcommand:sendafiletotheserver6.2.11Themgetandmputcommands:fetchorsendmultiplefiles6.2.12Theregetandreputcommands:resumingfiletransfers6.2.13Thedircommand:listremotefiles6.2.14Thechmodcommand:changepermissionsonremotefiles6.2.15Thedelcommand:deleteremotefiles6.2.16Themkdircommand:createremotedirectories6.2.17Thermdircommand:removeremotedirectories6.2.18Themvcommand:moveandrenameremotefiles6.2.19The!command:runalocalWindowscommand

6.2.1GeneralquotingrulesforPSFTPcommandsMostPSFTPcommandsareconsideredbythePSFTPcommandinterpreterasasequenceofwords,separatedbyspaces.Forexample,thecommandrenoldfilenamenewfilenamesplitsupintothreewords:ren(thecommandname),oldfilename(thenameofthefiletoberenamed),andnewfilename(thenewnametogivethefile).

Sometimesyouwillneedtospecifyfilenamesthatcontainspaces.Inordertodothis,youcansurroundthefilenamewithdoublequotes.Thisworksequallywellforlocalfilenamesandremotefilenames:

psftp>get"spaceyfilename.txt""saveitunderthisname.txt"

Thedoublequotesthemselveswillnotappearaspartofthefilenames;theyareremovedbyPSFTPandtheironlyeffectistostopthespacesinsidethemfromactingaswordseparators.

Ifyouneedtouseadoublequote(onsometypesofremotesystem,suchasUnix,youareallowedtousedoublequotesinfilenames),youcandothisbydoublingit.Thisworksbothinsideandoutsidedoublequotes.Forexample,thiscommand

psftp>ren""this"""afilewith""quotes""init"

willtakeafilewhosecurrentnameis"this"(withadoublequotecharacteratthebeginningandtheend)andrenameittoafilewhosenameisafilewith"quotes"init.

(TheoneexceptiontothePSFTPquotingrulesisthe!command,whichpassesitscommandlinestraighttoWindowswithoutsplittingitupintowordsatall.Seesection6.2.19.)

6.2.2WildcardsinPSFTPSeveralcommandsinPSFTPsupport‘wildcards’toselectmultiplefiles.

Forlocalfilespecifications(suchasthefirstargumenttoput),wildcardrulesforthelocaloperatingsystemareused.Forinstance,PSFTPrunningonWindowsmightrequiretheuseof*.*wherePSFTPonUnixwouldneed*.

Forremotefilespecifications(suchasthefirstargumenttoget),PSFTPusesastandardwildcardsyntax(similartoPOSIXwildcards):

*matchesanysequenceofcharacters(includingazero-lengthsequence).?matchesexactlyonecharacter.[abc]matchesexactlyonecharacterwhichcanbea,b,orc.

[a-z]matchesanycharacterintherangeatoz.

[^abc]matchesasinglecharacterthatisnota,b,orc.

Specialcases:[-a]matchesaliteralhyphen(-)ora;[^-a]matchesallothercharacters.[a^]matchesaliteralcaret(^)ora.

\(backslash)beforeanyoftheabovecharacters(oritself)removesthatcharacter'sspecialmeaning.

Aleadingperiod(.)onafilenameisnottreatedspecially,unlikeinsomeUnixcontexts;get*willfetchallfiles,whetherornottheystartwithaleadingperiod.

6.2.3Theopencommand:startasessionIfyoustartedPSFTPbydouble-clickingintheGUI,orjustbytypingpsftpatthecommandline,youwillneedtoopenaconnectiontoanSFTPserverbeforeyoucanissueanyothercommands(excepthelpandquit).

Tocreateaconnection,typeopenhost.name,orifyouneedtospecifyausernameaswellyoucantypeopenuser@host.name.Youcanoptionallyspecifyaportaswell:openuser@host.name22.

Onceyouhaveissuedthiscommand,youwillnotbeabletoissueitagain,evenifthecommandfails(forexample,ifyoumistypethehostnameortheconnectiontimesout).Soiftheconnectionisnotopenedsuccessfully,PSFTPwillterminateimmediately.

6.2.4Thequitcommand:endyoursessionWhenyouhavefinishedyoursession,typethecommandquittoclosetheconnection,terminatePSFTPandreturntothecommandline(orjustclosethePSFTPconsolewindowifyoustarteditfromtheGUI).

Youcanalsousethebyeandexitcommands,whichhaveexactlythesameeffect.

6.2.5Theclosecommand:closeyourconnectionIfyoujustwanttoclosethenetworkconnectionbutkeepPSFTPrunning,youcanusetheclosecommand.Youcanthenusetheopencommandtoopenanewconnection.

6.2.6Thehelpcommand:getquickonlinehelpIfyoutypehelp,PSFTPwillgiveashortlistoftheavailablecommands.

Ifyoutypehelpwithacommandname-forexample,helpget-thenPSFTPwillgiveashortpieceofhelponthatparticularcommand.

6.2.7Thecdandpwdcommands:changingtheremoteworkingdirectoryPSFTPmaintainsanotionofyour‘workingdirectory’ontheserver.Thisisthedefaultdirectorythatothercommandswilloperateon.Forexample,ifyoutypegetfilename.datthenPSFTPwilllookforfilename.datinyourremoteworkingdirectoryontheserver.

Tochangeyourremoteworkingdirectory,usethecdcommand.Ifyoudon'tprovideanargument,cdwillreturnyoutoyourhomedirectoryontheserver(moreprecisely,theremotedirectoryyouwereinatthestartoftheconnection).

Todisplayyourcurrentremoteworkingdirectory,typepwd.

6.2.8Thelcdandlpwdcommands:changingthelocalworkingdirectoryAswellashavingaworkingdirectoryontheremoteserver,PSFTPalsohasaworkingdirectoryonyourlocalmachine(justlikeanyotherWindowsprocess).Thisisthedefaultlocaldirectorythatothercommandswilloperateon.Forexample,ifyoutypegetfilename.datthenPSFTPwillsavetheresultingfileasfilename.datinyourlocalworkingdirectory.

Tochangeyourlocalworkingdirectory,usethelcdcommand.Todisplayyourcurrentlocalworkingdirectory,typelpwd.

6.2.9Thegetcommand:fetchafilefromtheserverTodownloadafilefromtheserverandstoreitonyourlocalPC,youusethegetcommand.

Initssimplestform,youjustusethiswithafilename:

getmyfile.dat

Ifyouwanttostorethefilelocallyunderadifferentname,specifythelocalfilenameaftertheremoteone:

getmyfile.datnewname.dat

Thiswillfetchthefileontheservercalledmyfile.dat,butwillsaveittoyourlocalmachineunderthenamenewname.dat.

Tofetchanentiredirectoryrecursively,youcanusethe-roption:

get-rmydir

get-rmydirnewname

(Ifyouwanttofetchafilewhosenamestartswithahyphen,youmayhavetousethe--specialargument,whichstopsgetfrominterpretinganythingasaswitchafterit.Forexample,‘get---silly-name-’.)

6.2.10Theputcommand:sendafiletotheserverTouploadafiletotheserverfromyourlocalPC,youusetheputcommand.

Initssimplestform,youjustusethiswithafilename:

putmyfile.dat

Ifyouwanttostorethefileremotelyunderadifferentname,specifytheremotefilenameafterthelocalone:

putmyfile.datnewname.dat

Thiswillsendthelocalfilecalledmyfile.dat,butwillstoreitontheserverunderthenamenewname.dat.

Tosendanentiredirectoryrecursively,youcanusethe-roption:

put-rmydir

put-rmydirnewname

(Ifyouwanttosendafilewhosenamestartswithahyphen,youmayhavetousethe--specialargument,whichstopsputfrominterpretinganythingasaswitchafterit.Forexample,‘put---silly-name-’.)

6.2.11Themgetandmputcommands:fetchorsendmultiplefilesmgetworksalmostexactlylikeget,exceptthatitallowsyoutospecifymorethanonefiletofetchatonce.Youcandothisintwoways:

bygivingtwoormoreexplicitfilenames(‘mgetfile1.txtfile2.txt’)byusingawildcard(‘mget*.txt’).

Everyargumenttomgetistreatedasthenameofafiletofetch(unlikeget,whichwillinterpretatmostoneargumentlikethat,andasecondargumentwillbetreatedasanalternativenameunderwhichtostoretheretrievedfile),orawildcardexpressionmatchingmorethanonefile.

The-rand--optionsfromgetarealsoavailablewithmget.

mputissimilartoput,withthesamedifferences.

6.2.12Theregetandreputcommands:resumingfiletransfersIfafiletransferfailshalfwaythrough,andyouendupwithhalfthefilestoredonyourdisk,youcanresumethefiletransferusingtheregetandreputcommands.Theseworkexactlylikethegetandputcommands,buttheycheckforthepresenceofthehalf-writtendestinationfileandstarttransferringfromwherethelastattemptleftoff.

Thesyntaxofregetandreputisexactlythesameasthesyntaxofgetandput:

regetmyfile.dat

regetmyfile.datnewname.dat

reget-rmydir

Thesecommandsareintendedmainlyforresuminginterruptedtransfers.Theyassumethattheremotefileordirectorystructurehasnotchangedinanyway;iftherehavebeenchanges,youmayendupwithcorruptedfiles.Inparticular,the-roptionwillnotpickupchangestofilesordirectoriesalreadytransferredinfull.

6.2.13Thedircommand:listremotefilesTolistthefilesinyourremoteworkingdirectory,justtypedir.

Youcanalsolistthecontentsofadifferentdirectorybytypingdirfollowedbythedirectoryname:

dir/home/fred

dirsources

Andyoucanlistasubsetofthecontentsofadirectorybyprovidingawildcard:

dir/home/fred/*.txt

dirsources/*.c

Thelscommandworksexactlythesamewayasdir.

6.2.14Thechmodcommand:changepermissionsonremotefilesPSFTPallowsyoutomodifythefilepermissionsonfilesanddirectoriesontheserver.Youdothisusingthechmodcommand,whichworksverymuchliketheUnixchmodcommand.

Thebasicsyntaxischmodmodesfile,wheremodesrepresentsamodificationtothefilepermissions,andfileisthefilenametomodify.Youcanspecifymultiplefilesorwildcards.Forexample:

chmodgo-rwx,u+wprivatefile

chmoda+rpublic*

chmod640groupfile1groupfile2

ThemodesparametercanbeasetofoctaldigitsintheUnixstyle.(Ifyoudon'tknowwhatthismeans,youprobablydon'twanttobeusingit!)Alternatively,itcanbealistofpermissionmodifications,separatedbycommas.Eachmodificationconsistsof:

Thepeopleaffectedbythemodification.Thiscanbeu(theowninguser),g(membersoftheowninggroup),oro(everybodyelse-‘others’),orsomecombinationofthose.Itcanalsobea(‘all’)toaffecteverybodyatonce.A+or-sign,indicatingwhetherpermissionsaretobeaddedorremoved.Theactualpermissionsbeingaddedorremoved.Thesecanber(permissiontoreadthefile),w(permissiontowritetothefile),andx(permissiontoexecutethefile,orinthecaseofadirectory,permissiontoaccessfileswithinthedirectory).

Sotheaboveexampleswoulddo:

Thefirstexample:go-rwxremovesread,writeandexecutepermissionsformembersoftheowninggroupandeverybodyelse(sotheonlypermissionsleftaretheonesforthefileowner).u+waddswritepermissionforthefileowner.Thesecondexample:a+raddsreadpermissionforeverybodytoall

filesanddirectoriesstartingwith‘public’.

Inadditiontoallthis,thereareafewextraspecialcasesforUnixsystems.Onnon-Unixsystemstheseareunlikelytobeuseful:

Youcanspecifyu+sandu-stoaddorremovetheUnixset-user-IDbit.Thisistypicallyonlyusefulforspecialpurposes;refertoyourUnixdocumentationifyou'renotsureaboutit.Youcanspecifyg+sandg-stoaddorremovetheUnixset-group-IDbit.Onafile,thisworkssimilarlytotheset-user-IDbit(seeyourUnixdocumentationagain);onadirectoryitensuresthatfilescreatedinthedirectoryareaccessiblebymembersofthegroupthatownsthedirectory.Youcanspecify+tand-ttoaddorremovetheUnix‘stickybit’.Whenappliedtoadirectory,thismeansthattheownerofafileinthatdirectorycandeletethefile(whereasnormallyonlytheownerofthedirectorywouldbeallowedto).

6.2.15Thedelcommand:deleteremotefilesTodeleteafileontheserver,typedelandthenthefilenameorfilenames:

deloldfile.dat

delfile1.txtfile2.txt

del*.o

Fileswillbedeletedwithoutfurtherprompting,evenifmultiplefilesarespecified.

delwillonlydeletefiles.Youcannotuseittodeletedirectories;usermdirforthat.

Thermcommandworksexactlythesamewayasdel.

6.2.16Themkdircommand:createremotedirectoriesTocreateadirectoryontheserver,typemkdirandthenthedirectoryname:

mkdirnewstuff

Youcanspecifymultipledirectoriestocreateatonce:

mkdirdir1dir2dir3

6.2.17Thermdircommand:removeremotedirectoriesToremoveadirectoryontheserver,typermdirandthenthedirectorynameornames:

rmdiroldstuff

rmdir*.oldancient

Directorieswillbedeletedwithoutfurtherprompting,evenifmultipledirectoriesarespecified.

MostSFTPserverswillprobablyrefusetoremoveadirectoryifthedirectoryhasanythinginit,soyouwillneedtodeletethecontentsfirst.

6.2.18Themvcommand:moveandrenameremotefilesTorenameasinglefileontheserver,typemv,thenthecurrentfilename,andthenthenewfilename:

mvoldfilenewname

Youcanalsomovethefileintoadifferentdirectoryandchangethename:

mvoldfiledir/newname

Tomoveoneormorefilesintoanexistingsubdirectory,specifythefiles(usingwildcardsifdesired),andthenthedestinationdirectory:

mvfiledir

mvfile1dir1/file2dir2

mv*.c*.h..

Therenameandrencommandsworkexactlythesamewayasmv.

6.2.19The!command:runalocalWindowscommandYoucanrunlocalWindowscommandsusingthe!command.ThisistheonlyPSFTPcommandthatisnotsubjecttothecommandquotingrulesgiveninsection6.2.1.Ifanycommandlinebeginswiththe!character,thentherestofthelinewillbepassedstraighttoWindowswithoutfurthertranslation.

Forexample,ifyouwanttomoveanexistingcopyofafileoutofthewaybeforedownloadinganupdatedversion,youmighttype:

psftp>!renmyfile.datmyfile.bak

psftp>getmyfile.dat

usingtheWindowsrencommandtorenamefilesonyourlocalPC.

6.3UsingpublickeyauthenticationwithPSFTPLikePuTTY,PSFTPcanauthenticateusingapublickeyinsteadofapassword.Therearethreewaysyoucandothis.

Firstly,PSFTPcanusePuTTYsavedsessionsinplaceofhostnames.Soyoumightdothis:

RunPuTTY,andcreateaPuTTYsavedsession(seesection4.1.2)whichspecifiesyourprivatekeyfile(seesection4.22.8).Youwillprobablyalsowanttospecifyausernametologinas(seesection4.14.1).InPSFTP,youcannowusethenameofthesessioninsteadofahostname:typepsftpsessionname,wheresessionnameisreplacedbythenameofyoursavedsession.

Secondly,youcansupplythenameofaprivatekeyfileonthecommandline,withthe-ioption.Seesection3.8.3.18formoreinformation.

Thirdly,PSFTPwillattempttoauthenticateusingPageantifPageantisrunning(seechapter9).Soyouwoulddothis:

EnsurePageantisrunning,andhasyourprivatekeystoredinit.SpecifyauserandhostnametoPSFTPasnormal.PSFTPwillautomaticallydetectPageantandtrytousethekeyswithinit.

Formoregeneralinformationonpublic-keyauthentication,seechapter8.

Chapter7:Usingthecommand-lineconnectiontoolPlinkPlinkisacommand-lineconnectiontoolsimilartoUNIXssh.Itismostlyusedforautomatedoperations,suchasmakingCVSaccessarepositoryonaremoteserver.

Plinkisprobablynotwhatyouwantifyouwanttorunaninteractivesessioninaconsolewindow.

7.1StartingPlink7.2UsingPlink

7.2.1UsingPlinkforinteractivelogins7.2.2UsingPlinkforautomatedconnections7.2.3Plinkcommandlineoptions

7.3UsingPlinkinbatchfilesandscripts7.4UsingPlinkwithCVS7.5UsingPlinkwithWinCVS

7.1StartingPlinkPlinkisacommandlineapplication.Thismeansthatyoucannotjustdouble-clickonitsicontorunitandinsteadyouhavetobringupaconsolewindow.InWindows95,98,andME,thisiscalledan‘MS-DOSPrompt’,andinWindowsNT,2000,andXP,itiscalleda‘CommandPrompt’.ItshouldbeavailablefromtheProgramssectionofyourStartMenu.

InordertousePlink,thefileplink.exewillneedeithertobeonyourPATHorinyourcurrentdirectory.ToaddthedirectorycontainingPlinktoyourPATHenvironmentvariable,typeintotheconsolewindow:

setPATH=C:\path\to\putty\directory;%PATH%

Thiswillonlyworkforthelifetimeofthatparticularconsolewindow.TosetyourPATHmorepermanentlyonWindowsNT,2000,andXP,usetheEnvironmenttaboftheSystemControlPanel.OnWindows95,98,andME,youwillneedtoedityourAUTOEXEC.BATtoincludeasetcommandliketheoneabove.

7.2UsingPlinkThissectiondescribesthebasicsofhowtousePlinkforinteractiveloginsandforautomatedprocesses.

Onceyou'vegotaconsolewindowtotypeinto,youcanjusttypeplinkonitsowntobringupausagemessage.ThistellsyoutheversionofPlinkyou'reusing,andgivesyouabriefsummaryofhowtousePlink:

Z:\sysosd>plink

Plink:command-lineconnectionutility

Release0.70

Usage:plink[options][user@]host[command]

("host"canalsobeaPuTTYsavedsessionname)

Options:

-Vprintversioninformationandexit

-pgpfpprintPGPkeyfingerprintsandexit

-vshowverbosemessages

-loadsessnameLoadsettingsfromsavedsession

-ssh-telnet-rlogin-raw-serial

forceuseofaparticularprotocol

-Pportconnecttospecifiedport

-luserconnectwithspecifiedusername

-batchdisableallinteractiveprompts

-proxycmdcommand

use'command'aslocalproxy

-sercfgconfiguration-string(e.g.19200,8,n,1,X)

Specifytheserialconfiguration(serialonly)

ThefollowingoptionsonlyapplytoSSHconnections:

-pwpasswloginwithspecifiedpassword

-D[listen-IP:]listen-port

DynamicSOCKS-basedportforwarding

-L[listen-IP:]listen-port:host:port

Forwardlocalporttoremoteaddress

-R[listen-IP:]listen-port:host:port

Forwardremoteporttolocaladdress

-X-xenable/disableX11forwarding

-A-aenable/disableagentforwarding

-t-Tenable/disableptyallocation

-1-2forceuseofparticularprotocolversion

-4-6forceuseofIPv4orIPv6

-Cenablecompression

-ikeyprivatekeyfileforuserauthentication

-noagentdisableuseofPageant

-agentenableuseofPageant

-hostkeyaa:bb:cc:...

manuallyspecifyahostkey(mayberepeated)

-mfilereadremotecommand(s)fromfile

-sremotecommandisanSSHsubsystem(SSH-2only)

-Ndon'tstartashell/command(SSH-2only)

-nchost:port

opentunnelinplaceofsession(SSH-2only)

-sshlogfile

-sshrawlogfile

logprotocoldetailstoafile

-shareexists

testwhetheraconnection-sharingupstreamexists

Oncethisworks,youarereadytousePlink.

7.2.1UsingPlinkforinteractivelogins7.2.2UsingPlinkforautomatedconnections7.2.3Plinkcommandlineoptions

7.2.3.1-batch:disableallinteractiveprompts7.2.3.2-s:remotecommandisSSHsubsystem7.2.3.3-shareexists:testforconnection-sharingupstream

7.2.1UsingPlinkforinteractiveloginsTomakeasimpleinteractiveconnectiontoaremoteserver,justtypeplinkandthenthehostname:

Z:\sysosd>plinklogin.example.com

DebianGNU/Linux2.2flunky.example.com

flunkylogin:

Youshouldthenbeabletologinasnormalandrunasession.Theoutputsentbytheserverwillbewrittenstraighttoyourcommandpromptwindow,whichwillmostlikelynotinterpretterminalcontrolcodesinthewaytheserverexpectsitto.Soifyourunanyfull-screenapplications,forexample,youcanexpecttoseestrangecharactersappearinginyourwindow.InteractiveconnectionslikethisarenotthemainpointofPlink.

Inordertoconnectwithadifferentprotocol,youcangivethecommandlineoptions-ssh,-telnet,-rloginor-raw.TomakeanSSHconnection,forexample:

Z:\sysosd>plink-sshlogin.example.com

loginas:

IfyouhavealreadysetupaPuTTYsavedsession,theninsteadofsupplyingahostname,youcangivethesavedsessionname.Thisallowsyoutousepublic-keyauthentication,specifyausername,andusemostoftheotherfeaturesofPuTTY:

Z:\sysosd>plinkmy-ssh-session

Sentusername"fred"

Authenticatingwithpublickey"fred@winbox"

Lastlogin:ThuDec619:25:332001from:0.0

fred@flunky:~$

(Youcanalsousethe-loadcommand-lineoptiontoloadasavedsession;seesection3.8.3.1.Ifyouuse-load,thesavedsessionexists,anditspecifiesahostname,youcannotalsospecifyahostoruser@hostargument-itwillbetreatedaspartoftheremotecommand.)

7.2.2UsingPlinkforautomatedconnectionsMoretypicallyPlinkisusedwiththeSSHprotocol,toenableyoutotalkdirectlytoaprogramrunningontheserver.TodothisyouhavetoensurePlinkisusingtheSSHprotocol.Youcandothisinseveralways:

Usethe-sshoptionasdescribedinsection7.2.1.SetupaPuTTYsavedsessionthatdescribestheserveryouareconnectingto,andthatalsospecifiestheprotocolasSSH.SettheWindowsenvironmentvariablePLINK_PROTOCOLtothewordssh.

UsuallyPlinkisnotinvokeddirectlybyauser,butrunautomaticallybyanotherprocess.ThereforeyoutypicallydonotwantPlinktopromptyouforausernameorapassword.

Next,youarelikelytoneedtoavoidthevariousinteractivepromptsPlinkcanproduce.Youmightbepromptedtoverifythehostkeyoftheserveryou'reconnectingto,toenterausername,ortoenterapassword.

ToavoidbeingpromptedfortheserverhostkeywhenusingPlinkforanautomatedconnection,youshouldfirstmakeamanualconnection(usingeitherofPuTTYorPlink)tothesameserver,verifythehostkey(seesection2.2formoreinformation),andselectYestoaddthehostkeytotheRegistry.Afterthat,Plinkcommandsconnectingtothatservershouldnotgiveahostkeypromptunlessthehostkeychanges.

Toavoidbeingpromptedforausername,youcan:

Usethe-loptiontospecifyausernameonthecommandline.Forexample,plinklogin.example.com-lfred.SetupaPuTTYsavedsessionthatdescribestheserveryouareconnectingto,andthatalsospecifiestheusernametologinas(seesection4.14.1).

Toavoidbeingpromptedforapassword,youshouldalmostcertainlysetuppublic-keyauthentication.(Seechapter8forageneralintroductiontopublic-keyauthentication.)Again,youcandothisintwoways:

SetupaPuTTYsavedsessionthatdescribestheserveryouareconnectingto,andthatalsospecifiesaprivatekeyfile(seesection4.22.8).Forthistoworkwithoutprompting,yourprivatekeywillneedtohavenopassphrase.StoretheprivatekeyinPageant.Seechapter9forfurtherinformation.

Onceyouhavedoneallthis,youshouldbeabletorunaremotecommandontheSSHservermachineandhaveitexecuteautomaticallywithnoprompting:

Z:\sysosd>plinklogin.example.com-lfredechohello,world

hello,world

Z:\sysosd>

Or,ifyouhavesetupasavedsessionwithalltheconnectiondetails:

Z:\sysosd>plinkmysessionechohello,world

hello,world

Z:\sysosd>

ThenyoucansetupotherprogramstorunthisPlinkcommandandtalktoitasifitwereaprocessontheservermachine.

7.2.3PlinkcommandlineoptionsPlinkacceptsallthegeneralcommandlineoptionssupportedbythePuTTYtools.Seesection3.8.3foradescriptionoftheseoptions.

Plinkalsosupportssomeofitsownoptions.ThefollowingsectionsdescribePlink'sspecificcommand-lineoptions.

7.2.3.1-batch:disableallinteractiveprompts7.2.3.2-s:remotecommandisSSHsubsystem7.2.3.3-shareexists:testforconnection-sharingupstream

7.2.3.1-batch:disableallinteractivepromptsIfyouusethe-batchoption,Plinkwillnevergiveaninteractivepromptwhileestablishingtheconnection.Iftheserver'shostkeyisinvalid,forexample(seesection2.2),thentheconnectionwillsimplybeabandonedinsteadofaskingyouwhattodonext.

ThismayhelpPlink'sbehaviourwhenitisusedinautomatedscripts:using-batch,ifsomethinggoeswrongatconnectiontime,thebatchjobwillfailratherthanhang.

7.2.3.2-s:remotecommandisSSHsubsystemIfyouspecifythe-soption,PlinkpassesthespecifiedcommandasthenameofanSSH‘subsystem’ratherthananordinarycommandline.

(ThisoptionisonlymeaningfulwiththeSSH-2protocol.)

7.2.3.3-shareexists:testforconnection-sharingupstreamThisoptiondoesnotmakeanewconnection;insteaditallowstestingforthepresenceofanexistingconnectionthatcanbeshared.(Seesection4.18.5formoreinformationaboutSSHconnectionsharing.)

APlinkinvocationoftheform:

plink-shareexists<session>

willtestwhetherthereiscurrentlyaviable‘upstream’forthesessioninquestion,whichcanbespecifiedusinganysyntaxyou'dnormallyusewithPlinktomakeanactualconnection(ahost/portnumber,abaresavedsessionname,-load,etc).Itreturnsazeroexitstatusifausable‘upstream’exists,nonzerootherwise.

(ThisoptionisonlymeaningfulwiththeSSH-2protocol.)

7.3UsingPlinkinbatchfilesandscriptsOnceyouhavesetupPlinktobeabletologintoaremoteserverwithoutanyinteractiveprompting(seesection7.2.2),youcanuseitforlotsofscriptingandbatchpurposes.Forexample,tostartabackuponaremotemachine,youmightuseacommandlike:

plinkroot@myserver/etc/backups/do-backup.sh

Orperhapsyouwanttofetchallsystemloglinesrelatingtoaparticularwebarea:

plinkmysessiongrep/~fred//var/log/httpd/access.log>fredlog

Anynon-interactivecommandyoucouldusefullyrunontheservercommandline,youcanruninabatchfileusingPlinkinthisway.

7.4UsingPlinkwithCVSTousePlinkwithCVS,youneedtosettheenvironmentvariableCVS_RSHtopointtoPlink:

setCVS_RSH=\path\to\plink.exe

Youalsoneedtoarrangetobeabletoconnecttoaremotehostwithoutanyinteractiveprompts,asdescribedinsection7.2.2.

YoushouldthenbeabletorunCVSasfollows:

cvs-d:ext:user@sessionname:/path/to/repositorycomodule

Ifyouspecifiedausernameinyoursavedsession,youdon'tevenneedtospecifythe‘user’partofthis,andyoucanjustsay:

cvs-d:ext:sessionname:/path/to/repositorycomodule

7.5UsingPlinkwithWinCVSPlinkcanalsobeusedwithWinCVS.Firstly,arrangeforPlinktobeabletoconnecttoaremotehostnon-interactively,asdescribedinsection7.2.2.

Then,inWinCVS,bringupthe‘Preferences’dialogueboxfromtheAdminmenu,andswitchtothe‘Ports’tab.Ticktheboxtherelabelled‘Checkforanalternatershname’andinthetextentryfieldtotherightenterthefullpathtoplink.exe.Select‘OK’onthe‘Preferences’dialoguebox.

Next,select‘CommandLine’fromtheWinCVS‘Admin’menu,andtypeaCVScommandasinsection7.4,forexample:

cvs-d:ext:user@hostname:/path/to/repositorycomodule

or(ifyou'reusingasavedsession):

cvs-d:ext:user@sessionname:/path/to/repositorycomodule

Selectthefolderyouwanttocheckouttowiththe‘ChangeFolder’button,andclick‘OK’tocheckoutyourmodule.Onceyou'vegotmodulescheckedout,WinCVSwillhappilyinvokeplinkfromtheGUIforCVSoperations.

Chapter8:UsingpublickeysforSSHauthentication

8.1Publickeyauthentication-anintroduction8.2UsingPuTTYgen,thePuTTYkeygenerator

8.2.1Generatinganewkey8.2.2Selectingthetypeofkey8.2.3Selectingthesize(strength)ofthekey8.2.4The‘Generate’button8.2.5The‘Keyfingerprint’box8.2.6Settingacommentforyourkey8.2.7Settingapassphraseforyourkey8.2.8Savingyourprivatekeytoadiskfile8.2.9Savingyourpublickeytoadiskfile8.2.10‘Publickeyforpastingintoauthorized_keysfile’8.2.11Reloadingaprivatekey8.2.12Dealingwithprivatekeysinotherformats

8.3Gettingreadyforpublickeyauthentication

8.1Publickeyauthentication-anintroductionPublickeyauthenticationisanalternativemeansofidentifyingyourselftoaloginserver,insteadoftypingapassword.Itismoresecureandmoreflexible,butmoredifficulttosetup.

Inconventionalpasswordauthentication,youproveyouarewhoyouclaimtobebyprovingthatyouknowthecorrectpassword.Theonlywaytoproveyouknowthepasswordistotelltheserverwhatyouthinkthepasswordis.Thismeansthatiftheserverhasbeenhacked,orspoofed(seesection2.2),anattackercanlearnyourpassword.

Publickeyauthenticationsolvesthisproblem.Yougenerateakeypair,consistingofapublickey(whicheverybodyisallowedtoknow)andaprivatekey(whichyoukeepsecretanddonotgivetoanybody).Theprivatekeyisabletogeneratesignatures.Asignaturecreatedusingyourprivatekeycannotbeforgedbyanybodywhodoesnothavethatkey;butanybodywhohasyourpublickeycanverifythataparticularsignatureisgenuine.

Soyougenerateakeypaironyourowncomputer,andyoucopythepublickeytotheserver.Then,whentheserverasksyoutoprovewhoyouare,PuTTYcangenerateasignatureusingyourprivatekey.Theservercanverifythatsignature(sinceithasyourpublickey)andallowyoutologin.Nowiftheserverishackedorspoofed,theattackerdoesnotgainyourprivatekeyorpassword;theyonlygainonesignature.Andsignaturescannotbere-used,sotheyhavegainednothing.

Thereisaproblemwiththis:ifyourprivatekeyisstoredunprotectedonyourowncomputer,thenanybodywhogainsaccesstothatwillbeabletogeneratesignaturesasiftheywereyou.Sotheywillbeabletologintoyourserverunderyouraccount.Forthisreason,yourprivatekeyisusuallyencryptedwhenitisstoredonyourlocalmachine,usingapassphraseofyourchoice.Inordertogenerateasignature,PuTTYmustdecryptthekey,soyouhavetotypeyourpassphrase.

Thiscanmakepublic-keyauthenticationlessconvenientthanpasswordauthentication:everytimeyoulogintotheserver,insteadoftypinga

shortpassword,youhavetotypealongerpassphrase.Onesolutiontothisistouseanauthenticationagent,aseparateprogramwhichholdsdecryptedprivatekeysandgeneratessignaturesonrequest.PuTTY'sauthenticationagentiscalledPageant.WhenyoubeginaWindowssession,youstartPageantandloadyourprivatekeyintoit(typingyourpassphraseonce).Fortherestofyoursession,youcanstartPuTTYanynumberoftimesandPageantwillautomaticallygeneratesignatureswithoutyouhavingtodoanything.WhenyoucloseyourWindowssession,Pageantshutsdown,withouteverhavingstoredyourdecryptedprivatekeyondisk.Manypeoplefeelthisisagoodcompromisebetweensecurityandconvenience.Seechapter9forfurtherdetails.

Thereismorethanonepublic-keyalgorithmavailable.ThemostcommonareRSAandECDSA,butothersexist,notablyDSA(otherwiseknownasDSS),theUSA'sfederalDigitalSignatureStandard.ThekeytypessupportedbyPuTTYaredescribedinsection8.2.2.

8.2UsingPuTTYgen,thePuTTYkeygeneratorPuTTYgenisakeygenerator.ItgeneratespairsofpublicandprivatekeystobeusedwithPuTTY,PSCP,andPlink,aswellasthePuTTYauthenticationagent,Pageant(seechapter9).PuTTYgengeneratesRSA,DSA,ECDSA,andEd25519keys.

WhenyourunPuTTYgenyouwillseeawindowwhereyouhavetwochoices:‘Generate’,togenerateanewpublic/privatekeypair,or‘Load’toloadinanexistingprivatekey.

8.2.1Generatinganewkey8.2.2Selectingthetypeofkey8.2.3Selectingthesize(strength)ofthekey8.2.4The‘Generate’button8.2.5The‘Keyfingerprint’box8.2.6Settingacommentforyourkey8.2.7Settingapassphraseforyourkey8.2.8Savingyourprivatekeytoadiskfile8.2.9Savingyourpublickeytoadiskfile8.2.10‘Publickeyforpastingintoauthorized_keysfile’8.2.11Reloadingaprivatekey8.2.12Dealingwithprivatekeysinotherformats

8.2.1GeneratinganewkeyThisisageneraloutlineoftheprocedureforgeneratinganewkeypair.Thefollowingsectionsdescribetheprocessinmoredetail.

First,youneedtoselectwhichtypeofkeyyouwanttogenerate,andalsoselectthestrengthofthekey.Thisisdescribedinmoredetailinsection8.2.2andsection8.2.3.Thenpressthe‘Generate’button,toactuallygeneratethekey.Section8.2.4describesthisstep.Onceyouhavegeneratedthekey,selectacommentfield(section8.2.6)andapassphrase(section8.2.7).Nowyou'rereadytosavetheprivatekeytodisk;pressthe‘Saveprivatekey’button.(Seesection8.2.8).

Yourkeypairisnowreadyforuse.Youmayalsowanttocopythepublickeytoyourserver,eitherbycopyingitoutofthe‘Publickeyforpastingintoauthorized_keysfile’box(seesection8.2.10),orbyusingthe‘Savepublickey’button(section8.2.9).However,youdon'tneedtodothisimmediately;ifyouwant,youcanloadtheprivatekeybackintoPuTTYgenlater(seesection8.2.11)andthepublickeywillbeavailableforcopyingandpastingagain.

Section8.3describesthetypicalprocessofconfiguringPuTTYtoattemptpublic-keyauthentication,andconfiguringyourSSHservertoacceptit.

8.2.2SelectingthetypeofkeyBeforegeneratingakeypairusingPuTTYgen,youneedtoselectwhichtypeofkeyyouneed.PuTTYgencurrentlysupportsthesetypesofkey:

AnRSAkeyforusewiththeSSH-1protocol.AnRSAkeyforusewiththeSSH-2protocol.ADSAkeyforusewiththeSSH-2protocol.AnECDSA(ellipticcurveDSA)keyforusewiththeSSH-2protocol.AnEd25519key(anotherellipticcurvealgorithm)forusewiththeSSH-2protocol.

TheSSH-1protocolonlysupportsRSAkeys;ifyouwillbeconnectingusingtheSSH-1protocol,youmustselectthefirstkeytypeoryourkeywillbecompletelyuseless.

TheSSH-2protocolsupportsmorethanonekeytype.ThetypessupportedbyPuTTYareRSA,DSA,ECDSA,andEd25519.

8.2.3Selectingthesize(strength)ofthekeyThe‘Numberofbits’inputboxallowsyoutochoosethestrengthofthekeyPuTTYgenwillgenerate.

ForRSA,2048bitsshouldcurrentlybesufficientformostpurposes.ForECDSA,only256,384,and521bitsaresupported.(ECDSAoffersequivalentsecuritytoRSAwithsmallerkeysizes.)ForEd25519,theonlyvalidsizeis256bits.

8.2.4The‘Generate’buttonOnceyouhavechosenthetypeofkeyyouwant,andthestrengthofthekey,pressthe‘Generate’buttonandPuTTYgenwillbegintheprocessofactuallygeneratingthekey.

First,aprogressbarwillappearandPuTTYgenwillaskyoutomovethemousearoundtogeneraterandomness.WavethemouseincirclesovertheblankareainthePuTTYgenwindow,andtheprogressbarwillgraduallyfillupasPuTTYgencollectsenoughrandomness.Youdon'tneedtowavethemouseinparticularlyimaginativepatterns(althoughitcan'thurt);PuTTYgenwillcollectenoughrandomnessjustfromthefinedetailofexactlyhowfarthemousehasmovedeachtimeWindowssamplesitsposition.

Whentheprogressbarreachestheend,PuTTYgenwillbegincreatingthekey.Theprogressbarwillresettothestart,andgraduallymoveupagaintotracktheprogressofthekeygeneration.Itwillnotmoveevenly,andmayoccasionallyslowdowntoastop;thisisunfortunatelyunavoidable,becausekeygenerationisarandomprocessanditisimpossibletoreliablypredicthowlongitwilltake.

Whenthekeygenerationiscomplete,anewsetofcontrolswillappearinthewindowtoindicatethis.

8.2.5The‘Keyfingerprint’boxThe‘Keyfingerprint’boxshowsyouafingerprintvalueforthegeneratedkey.Thisisderivedcryptographicallyfromthepublickeyvalue,soitdoesn'tneedtobekeptsecret;itissupposedtobemoremanageableforhumanbeingsthanthepublickeyitself.

Thefingerprintvalueisintendedtobecryptographicallysecure,inthesensethatitiscomputationallyinfeasibleforsomeonetoinventasecondkeywiththesamefingerprint,ortofindakeywithaparticularfingerprint.Sosomeutilities,suchasthePageantkeylistbox(seesection9.2.1)andtheUnixssh-addutility,willlistkeyfingerprintsratherthanthewholepublickey.

8.2.6SettingacommentforyourkeyIfyouhavemorethanonekeyandusethemfordifferentpurposes,youdon'tneedtomemorisethekeyfingerprintsinordertotellthemapart.PuTTYgenallowsyoutoenteracommentforyourkey,whichwillbedisplayedwheneverPuTTYorPageantasksyouforthepassphrase.

Thedefaultcommentformat,ifyoudon'tspecifyone,containsthekeytypeandthedateofgeneration,suchasrsa-key-20011212.Anothercommonlyusedapproachistouseyournameandthenameofthecomputerthekeywillbeusedon,suchassimon@simons-pc.

Toalterthekeycomment,justtypeyourcommenttextintothe‘Keycomment’boxbeforesavingtheprivatekey.Ifyouwanttochangethecommentlater,youcanloadtheprivatekeybackintoPuTTYgen,changethecomment,andsaveitagain.

8.2.7SettingapassphraseforyourkeyThe‘Keypassphrase’and‘Confirmpassphrase’boxesallowyoutochooseapassphraseforyourkey.Thepassphrasewillbeusedtoencryptthekeyondisk,soyouwillnotbeabletousethekeywithoutfirstenteringthepassphrase.

Whenyousavethekey,PuTTYgenwillcheckthatthe‘Keypassphrase’and‘Confirmpassphrase’boxesbothcontainexactlythesamepassphrase,andwillrefusetosavethekeyotherwise.

Ifyouleavethepassphrasefieldsblank,thekeywillbesavedunencrypted.Youshouldnotdothiswithoutgoodreason;ifyoudo,yourprivatekeyfileondiskwillbeallanattackerneedstogainaccesstoanymachineconfiguredtoacceptthatkey.Ifyouwanttobeabletologinwithouthavingtotypeapassphraseeverytime,youshouldconsiderusingPageant(chapter9)sothatyourdecryptedkeyisonlyheldinmemoryratherthanondisk.

Underspecialcircumstancesyoumaygenuinelyneedtouseakeywithnopassphrase;forexample,ifyouneedtorunanautomatedbatchscriptthatneedstomakeanSSHconnection,youcan'tbetheretotypethepassphrase.Inthiscasewerecommendyougenerateaspecialkeyforeachspecificbatchscript(orwhatever)thatneedsone,andontheserversideyoushouldarrangethateachkeyisrestrictedsothatitcanonlybeusedforthatspecificpurpose.ThedocumentationforyourSSHservershouldexplainhowtodothis(itwillprobablyvarybetweenservers).

Choosingagoodpassphraseisdifficult.Justasyoushouldn'tuseadictionarywordasapasswordbecauseit'seasyforanattackertorunthroughawholedictionary,youshouldnotuseasonglyric,quotationorotherwell-knownsentenceasapassphrase.DiceWare(www.diceware.com)recommendsusingatleastfivewordseachgeneratedrandomlybyrollingfivedice,whichgivesover2^64possiblepassphrasesandisprobablynotabadscheme.Ifyouwantyourpassphrasetomakegrammaticalsense,thiscutsdownthepossibilitiesalotandyoushouldusealongeroneasaresult.

Donotforgetyourpassphrase.Thereisnowaytorecoverit.

8.2.8SavingyourprivatekeytoadiskfileOnceyouhavegeneratedakey,setacommentfieldandsetapassphrase,youarereadytosaveyourprivatekeytodisk.

Pressthe‘Saveprivatekey’button.PuTTYgenwillputupadialogboxaskingyouwheretosavethefile.Selectadirectory,typeinafilename,andpress‘Save’.

ThisfileisinPuTTY'snativeformat(*.PPK);itistheoneyouwillneedtotellPuTTYtouseforauthentication(seesection4.22.8)ortellPageanttoload(seesection9.2.2).

8.2.9SavingyourpublickeytoadiskfileRFC4716specifiesastandardformatforstoringSSH-2publickeysondisk.SomeSSHservers(suchasssh.com's)requireapublickeyinthisformatinordertoacceptauthenticationwiththecorrespondingprivatekey.(Others,suchasOpenSSH,useadifferentformat;seesection8.2.10.)

TosaveyourpublickeyintheSSH-2standardformat,pressthe‘Savepublickey’buttoninPuTTYgen.PuTTYgenwillputupadialogboxaskingyouwheretosavethefile.Selectadirectory,typeinafilename,andpress‘Save’.

YouwillthenprobablywanttocopythepublickeyfiletoyourSSHservermachine.Seesection8.3forgeneralinstructionsonconfiguringpublic-keyauthenticationonceyouhavegeneratedakey.

IfyouusethisoptionwithanSSH-1key,thefilePuTTYgensaveswillcontainexactlythesametextthatappearsinthe‘Publickeyforpasting’box.ThisistheonlyexistingstandardforSSH-1publickeys.

8.2.10‘Publickeyforpastingintoauthorized_keysfile’AllSSH-1serversrequireyourpublickeytobegiventoitinaone-lineformatbeforeitwillacceptauthenticationwithyourprivatekey.TheOpenSSHserveralsorequiresthisforSSH-2.

The‘Publickeyforpastingintoauthorized_keysfile’givesthepublic-keydatainthecorrectone-lineformat.Typicallyyouwillwanttoselecttheentirecontentsoftheboxusingthemouse,pressCtrl+Ctocopyittotheclipboard,andthenpastethedataintoaPuTTYsessionwhichisalreadyconnectedtotheserver.

Seesection8.3forgeneralinstructionsonconfiguringpublic-keyauthenticationonceyouhavegeneratedakey.

8.2.11ReloadingaprivatekeyPuTTYgenallowsyoutoloadanexistingprivatekeyfileintomemory.Ifyoudothis,youcanthenchangethepassphraseandcommentbeforesavingitagain;youcanalsomakeextracopiesofthepublickey.

Toloadanexistingkey,pressthe‘Load’button.PuTTYgenwillputupadialogboxwhereyoucanbrowsearoundthefilesystemandfindyourkeyfile.Onceyouselectthefile,PuTTYgenwillaskyouforapassphrase(ifnecessary)andwillthendisplaythekeydetailsinthesamewayasifithadjustgeneratedthekey.

IfyouusetheLoadcommandtoloadaforeignkeyformat,itwillwork,butyouwillseeamessageboxwarningyouthatthekeyyouhaveloadedisnotaPuTTYnativekey.Seesection8.2.12forinformationaboutimportingforeignkeyformats.

8.2.12DealingwithprivatekeysinotherformatsMostSSH-1clientsuseastandardformatforstoringprivatekeysondisk.PuTTYusesthisformataswell;soifyouhavegeneratedanSSH-1privatekeyusingOpenSSHorssh.com'sclient,youcanuseitwithPuTTY,andviceversa.

However,SSH-2privatekeyshavenostandardformat.OpenSSHandssh.comhavedifferentformats,andPuTTY'sisdifferentagain.Soakeygeneratedwithoneclientcannotimmediatelybeusedwithanother.

Usingthe‘Import’commandfromthe‘Conversions’menu,PuTTYgencanloadSSH-2privatekeysinOpenSSH'sformatandssh.com'sformat.Onceyouhaveloadedoneofthesekeytypes,youcanthensaveitbackoutasaPuTTY-formatkey(*.PPK)sothatyoucanuseitwiththePuTTYsuite.Thepassphrasewillbeunchangedbythisprocess(unlessyoudeliberatelychangeit).Youmaywanttochangethekeycommentbeforeyousavethekey,sinceOpenSSH'sSSH-2keyformatcontainsnospaceforacommentandssh.com'sdefaultcommentformatislongandverbose.

PuTTYgencanalsoexportprivatekeysinOpenSSHformatandinssh.comformat.Todoso,selectoneofthe‘Export’optionsfromthe‘Conversions’menu.Exportingakeyworksexactlylikesavingit(seesection8.2.8)-youneedtohavetypedyourpassphraseinbeforehand,andyouwillbewarnedifyouareabouttosaveakeywithoutapassphrase.

ForOpenSSHtherearetwooptions.ModernOpenSSHactuallyhastwoformatsitusesforstoringprivatekeys.‘ExportOpenSSHkey’willautomaticallychoosetheoldestformatsupportedforthekeytype,formaximumbackwardcompatibilitywitholderversionsofOpenSSH;fornewerkeytypeslikeEd25519,itwillusethenewerformatasthatistheonlylegaloption.IfyouhavesomespecificreasonforwantingtouseOpenSSH'snewerformatevenforRSA,DSA,orECDSAkeys,youcanchoose‘ExportOpenSSHkey(forcenewfileformat)’.

NotethatsinceonlySSH-2keyscomeindifferentformats,theexport

optionsarenotavailableifyouhavegeneratedanSSH-1key.

8.3GettingreadyforpublickeyauthenticationConnecttoyourSSHserverusingPuTTYwiththeSSHprotocol.Whentheconnectionsucceedsyouwillbepromptedforyourusernameandpasswordtologin.Onceloggedin,youmustconfiguretheservertoacceptyourpublickeyforauthentication:

IfyourserverisusingtheSSH-1protocol,youshouldchangeintothe.sshdirectoryandopenthefileauthorized_keyswithyourfavouriteeditor.(Youmayhavetocreatethisfileifthisisthefirstkeyyouhaveputinit).ThenswitchtothePuTTYgenwindow,selectallofthetextinthe‘Publickeyforpastingintoauthorized_keysfile’box(seesection8.2.10),andcopyittotheclipboard(Ctrl+C).Then,switchbacktothePuTTYwindowandinsertthedataintotheopenfile,makingsureitendsupallononeline.Savethefile.IfyourserverisOpenSSHandisusingtheSSH-2protocol,youshouldfollowthesameinstructions,exceptthatinearlierversionsofOpenSSH2thefilemightbecalledauthorized_keys2.(Inmodernversionsthesameauthorized_keysfileisusedforbothSSH-1andSSH-2keys.)Ifyourserverisssh.com'sproductandisusingSSH-2,youneedtosaveapublickeyfilefromPuTTYgen(seesection8.2.9),andcopythatintothe.ssh2directoryontheserver.Thenyoushouldgointothat.ssh2directory,andedit(orcreate)afilecalledauthorization.InthisfileyoushouldputalinelikeKeymykey.pub,withmykey.pubreplacedbythenameofyourkeyfile.ForotherSSHserversoftware,youshouldrefertothemanualforthatserver.

Youmayalsoneedtoensurethatyourhomedirectory,your.sshdirectory,andanyotherfilesinvolved(suchasauthorized_keys,authorized_keys2orauthorization)arenotgroup-writableorworld-writable.Youcantypicallydothisbyusingacommandsuchas

chmodgo-w$HOME$HOME/.ssh$HOME/.ssh/authorized_keys

Yourservershouldnowbeconfiguredtoacceptauthenticationusingyourprivatekey.NowyouneedtoconfigurePuTTYtoattemptauthentication

usingyourprivatekey.Youcandothisinanyofthreeways:

SelecttheprivatekeyinPuTTY'sconfiguration.Seesection4.22.8fordetails.Specifythekeyfileonthecommandlinewiththe-ioption.Seesection3.8.3.18fordetails.LoadtheprivatekeyintoPageant(seechapter9).InthiscasePuTTYwillautomaticallytrytouseitforauthenticationifitcan.

Chapter9:UsingPageantforauthenticationPageantisanSSHauthenticationagent.Itholdsyourprivatekeysinmemory,alreadydecoded,sothatyoucanusethemoftenwithoutneedingtotypeapassphrase.

9.1GettingstartedwithPageant9.2ThePageantmainwindow

9.2.1Thekeylistbox9.2.2The‘AddKey’button9.2.3The‘RemoveKey’button

9.3ThePageantcommandline9.3.1MakingPageantautomaticallyloadkeysonstartup9.3.2MakingPageantrunanotherprogram

9.4Usingagentforwarding9.5Securityconsiderations

9.1GettingstartedwithPageantBeforeyourunPageant,youneedtohaveaprivatekeyin*.PPKformat.Seechapter8tofindouthowtogenerateanduseone.

WhenyourunPageant,itwillputaniconofacomputerwearingahatintotheSystemtray.Itwillthensitanddonothing,untilyouloadaprivatekeyintoit.

IfyouclickthePageanticonwiththerightmousebutton,youwillseeamenu.Select‘ViewKeys’fromthismenu.ThePageantmainwindowwillappear.(Youcanalsobringthiswindowupbydouble-clickingonthePageanticon.)

ThePageantwindowcontainsalistbox.ThisshowstheprivatekeysPageantisholding.WhenyoustartPageant,ithasnokeys,sothelistboxwillbeempty.Afteryouaddoneormorekeys,theywillshowupinthelistbox.

ToaddakeytoPageant,pressthe‘AddKey’button.Pageantwillbringupafiledialog,labelled‘SelectPrivateKeyFile’.Findyourprivatekeyfileinthisdialog,andpress‘Open’.

Pageantwillnowloadtheprivatekey.Ifthekeyisprotectedbyapassphrase,Pageantwillaskyoutotypethepassphrase.Whenthekeyhasbeenloaded,itwillappearinthelistinthePageantwindow.

NowstartPuTTYandopenanSSHsessiontoasitethatacceptsyourkey.PuTTYwillnoticethatPageantisrunning,retrievethekeyautomaticallyfromPageant,anduseittoauthenticate.YoucannowopenasmanyPuTTYsessionsasyoulikewithouthavingtotypeyourpassphraseagain.

(PuTTYcanbeconfigurednottotrytousePageant,butitwilltrybydefault.Seesection4.22.3andsection3.8.3.9formoreinformation.)

WhenyouwanttoshutdownPageant,clicktherightbuttononthePageanticonintheSystemtray,andselect‘Exit’fromthemenu.ClosingthePageantmainwindowdoesnotshutdownPageant.

9.2ThePageantmainwindowThePageantmainwindowappearswhenyouleft-clickonthePageantsystemtrayicon,oralternativelyright-clickandselect‘ViewKeys’fromthemenu.YoucanuseittokeeptrackofwhatkeysarecurrentlyloadedintoPageant,andtoaddnewonesorremovetheexistingkeys.

9.2.1Thekeylistbox9.2.2The‘AddKey’button9.2.3The‘RemoveKey’button

9.2.1ThekeylistboxThelargelistboxinthePageantmainwindowliststheprivatekeysthatarecurrentlyloadedintoPageant.Thelistmightlooksomethinglikethis:

ssh-rsa204822:d6:69:c9:22:51:ac:cb:b9:15:67:47:f7:65:6d:d7k1

ssh-dss2048e4:6c:69:f3:4f:fc:cf:fc:96:c0:88:34:a7:1e:59:d7k2

Foreachkey,thelistboxwilltellyou:

Thetypeofthekey.Currently,thiscanbessh1(anRSAkeyforusewiththeSSH-1protocol),ssh-rsa(anRSAkeyforusewiththeSSH-2protocol),ssh-dss(aDSAkeyforusewiththeSSH-2protocol),ecdsa-sha2-*(anECDSAkeyforusewiththeSSH-2protocol),orssh-ed25519(anEd25519keyforusewiththeSSH-2protocol).Thesize(inbits)ofthekey.Thefingerprintforthepublickey.ThisshouldbethesamefingerprintgivenbyPuTTYgen,and(hopefully)alsothesamefingerprintshownbyremoteutilitiessuchasssh-keygenwhenappliedtoyourauthorized_keysfile.Thecommentattachedtothekey.

9.2.2The‘AddKey’buttonToaddakeytoPageantbyreadingitoutofalocaldiskfile,pressthe‘AddKey’buttoninthePageantmainwindow,oralternativelyright-clickonthePageanticoninthesystemtrayandselect‘AddKey’fromthere.

Pageantwillbringupafiledialog,labelled‘SelectPrivateKeyFile’.Findyourprivatekeyfileinthisdialog,andpress‘Open’.Ifyouwanttoaddmorethanonekeyatonce,youcanselectmultiplefilesusingShift-click(toselectseveraladjacentfiles)orCtrl-click(toselectnon-adjacentfiles).

Pageantwillnowloadtheprivatekey(s).Ifakeyisprotectedbyapassphrase,Pageantwillaskyoutotypethepassphrase.

(ThisisnottheonlywaytoaddaprivatekeytoPageant.Youcanalsoaddonefromaremotesystembyusingagentforwarding;seesection9.4fordetails.)

9.2.3The‘RemoveKey’buttonIfyouneedtoremoveakeyfromPageant,selectthatkeyinthelistbox,andpressthe‘RemoveKey’button.Pageantwillremovethekeyfromitsmemory.

Youcanapplythistokeysyouaddedusingthe‘AddKey’button,ortokeysyouaddedremotelyusingagentforwarding(seesection9.4);itmakesnodifference.

9.3ThePageantcommandlinePageantcanbemadetodothingsautomaticallywhenitstartsup,byspecifyinginstructionsonitscommandline.Ifyou'restartingPageantfromtheWindowsGUI,youcanarrangethisbyeditingthepropertiesoftheWindowsshortcutthatitwasstartedfrom.

IfPageantisalreadyrunning,invokingitagainwiththeoptionsbelowcausesactionstobeperformedwiththeexistinginstance,notanewone.

9.3.1MakingPageantautomaticallyloadkeysonstartup9.3.2MakingPageantrunanotherprogram

9.3.1MakingPageantautomaticallyloadkeysonstartupPageantcanautomaticallyloadoneormoreprivatekeyswhenitstartsup,ifyouprovidethemonthePageantcommandline.Yourcommandlinemightthenlooklike:

C:\PuTTY\pageant.exed:\main.ppkd:\secondary.ppk

Ifthekeysarestoredencrypted,Pageantwillrequestthepassphrasesonstartup.

IfPageantisalreadyrunning,thissyntaxloadskeysintotheexistingPageant.

9.3.2MakingPageantrunanotherprogramYoucanarrangeforPageanttostartanotherprogramonceithasinitialiseditselfandloadedanykeysspecifiedonitscommandline.Thisprogram(perhapsaPuTTY,oraWinCVSmakinguseofPlink,orwhatever)willthenbeabletousethekeysPageanthasloaded.

Youdothisbyspecifyingthe-coptionfollowedbythecommand,likethis:

C:\PuTTY\pageant.exed:\main.ppk-cC:\PuTTY\putty.exe

9.4UsingagentforwardingAgentforwardingisamechanismthatallowsapplicationsonyourSSHservermachinetotalktotheagentonyourclientmachine.

Notethatatpresent,agentforwardinginSSH-2isonlyavailablewhenyourSSHserverisOpenSSH.Thessh.comserverusesadifferentagentprotocol,whichPuTTYdoesnotyetsupport.

Toenableagentforwarding,firststartPageant.ThensetupaPuTTYSSHsessioninwhich‘Allowagentforwarding’isenabled(seesection4.22.6).Openthesessionasnormal.(Alternatively,youcanusethe-Acommandlineoption;seesection3.8.3.10fordetails.)

Ifthishasworked,yourapplicationsontheservershouldnowhaveaccesstoaUnixdomainsocketwhichtheSSHserverwillforwardbacktoPuTTY,andPuTTYwillforwardontotheagent.Tocheckthatthishasactuallyhappened,youcantrythiscommandonUnixservermachines:

unixbox:~$echo$SSH_AUTH_SOCK

/tmp/ssh-XXNP18Jz/agent.28794

unixbox:~$

Iftheresultlinecomesupblank,agentforwardinghasnotbeenenabledatall.

NowifyourunsshontheserveranduseittoconnectthroughtoanotherserverthatacceptsoneofthekeysinPageant,youshouldbeabletologinwithoutapassword:

unixbox:~$ssh-votherunixbox

[...]

debug:nextauthmethodtotryispublickey

debug:userauth_pubkey_agent:tryingagentkeymy-putty-key

debug:ssh-userauth2successful:methodpublickey

[...]

IfyouenableagentforwardingonthatSSHconnectionaswell(seethemanualforyourserver-sideSSHclienttofindouthowtodothis),yourauthenticationkeyswillstillbeavailableonthenextmachineyouconnectto-twoSSHconnectionsawayfromwherethey'reactuallystored.

Inaddition,ifyouhaveaprivatekeyononeoftheSSHservers,youcansenditallthewaybacktoPageantusingthelocalssh-addcommand:

unixbox:~$ssh-add~/.ssh/id_rsa

Needpassphrasefor/home/fred/.ssh/id_rsa

Enterpassphrasefor/home/fred/.ssh/id_rsa:

Identityadded:/home/fred/.ssh/id_rsa(/home/simon/.ssh/id_rsa)

unixbox:~$

andthenit'savailabletoeverymachinethathasagentforwardingavailable(notjusttheonesdownstreamoftheplaceyouaddedit).

9.5SecurityconsiderationsUsingPageantforpublic-keyauthenticationgivesyoutheconvenienceofbeingabletoopenmultipleSSHsessionswithouthavingtotypeapassphraseeverytime,butalsogivesyouthesecuritybenefitofneverstoringadecryptedprivatekeyondisk.Manypeoplefeelthisisagoodcompromisebetweensecurityandconvenience.

Itisacompromise,however.HoldingyourdecryptedprivatekeysinPageantisbetterthanstoringthemineasy-to-finddiskfiles,butstilllesssecurethannotstoringthemanywhereatall.Thisisfortworeasons:

Windowsunfortunatelyprovidesnowaytoprotectpiecesofmemoryfrombeingwrittentothesystemswapfile.SoifPageantisholdingyourprivatekeysforalongperiodoftime,it'spossiblethatdecryptedprivatekeydatamaybewrittentothesystemswapfile,andanattackerwhogainedaccesstoyourharddisklateronmightbeabletorecoverthatdata.(However,ifyoustoredanunencryptedkeyinadiskfiletheywouldcertainlybeabletorecoverit.)Although,likemostmodernoperatingsystems,Windowspreventsprogramsfromaccidentallyaccessingoneanother'smemoryspace,itdoesallowprogramstoaccessoneanother'smemoryspacedeliberately,forspecialpurposessuchasdebugging.Thismeansthatifyouallowavirus,trojan,orothermaliciousprogramontoyourWindowssystemwhilePageantisrunning,itcouldaccessthememoryofthePageantprocess,extractyourdecryptedauthenticationkeys,andsendthembacktoitsmaster.

Similarly,useofagentforwardingisasecurityimprovementonothermethodsofone-touchauthentication,butnotperfect.HoldingyourkeysinPageantonyourWindowsboxhasasecurityadvantageoverholdingthemontheremoteservermachineitself(eitherinanagentorjustunencryptedondisk),becauseiftheservermachineeverseesyourunencryptedprivatekeythenthesysadminoranyonewhocracksthemachinecanstealthekeysandpretendtobeyouforaslongastheywant.

However,thesysadminoftheservermachinecanalwayspretendtobe

youonthatmachine.Soifyouforwardyouragenttoaservermachine,thenthesysadminofthatmachinecanaccesstheforwardedagentconnectionandrequestsignaturesfromanyofyourprivatekeys,andcanthereforelogintoothermachinesasyou.Theycanonlydothistoalimitedextent-whentheagentforwardingdisappearstheylosetheability-butusingPageantdoesn'tactuallypreventthesysadmin(orhackers)ontheserverfromdoingthis.

Therefore,ifyoudon'ttrustthesysadminofaservermachine,youshouldneveruseagentforwardingtothatmachine.(Ofcourseyoualsoshouldn'tstoreprivatekeysonthatmachine,typepassphrasesintoit,orlogintoothermachinesfromitinanywayatall;Pageantishardlyuniqueinthisrespect.)

Chapter10:CommonerrormessagesThischapterlistsanumberofcommonerrormessageswhichPuTTYanditsassociatedtoolscanproduce,andexplainswhattheymeaninmoredetail.

Wedonotattempttolistallerrormessageshere:therearemanywhichshouldneveroccur,andsomewhichshouldbeself-explanatory.Ifyougetanerrormessagewhichisnotlistedinthischapterandwhichyoudon'tunderstand,reportittousasabug(seeappendixB)andwewilladddocumentationforit.

10.1‘Theserver'shostkeyisnotcachedintheregistry’10.2‘WARNING-POTENTIALSECURITYBREACH!’10.3‘SSHprotocolversion2requiredbyourconfigurationbutserveronlyprovides(old,insecure)SSH-1’10.4‘Thefirstciphersupportedbytheserveris...belowtheconfiguredwarningthreshold’10.5‘Serversentdisconnectmessagetype2(protocolerror):"Toomanyauthenticationfailuresforroot"’10.6‘Outofmemory’10.7‘Internalerror’,‘Internalfault’,‘Assertionfailed’10.8‘Unabletousethisprivatekeyfile’,‘Couldn'tloadprivatekey’,‘Keyisofwrongtype’10.9‘Serverrefusedourpublickey’or‘Keyrefused’10.10‘Accessdenied’,‘Authenticationrefused’10.11‘Nosupportedauthenticationmethodsavailable’10.12‘IncorrectCRCreceivedonpacket’or‘IncorrectMACreceivedonpacket’10.13‘Incomingpacketwasgarbledondecryption’10.14‘PuTTYX11proxy:variouserrors’10.15‘Networkerror:Softwarecausedconnectionabort’10.16‘Networkerror:Connectionresetbypeer’10.17‘Networkerror:Connectionrefused’10.18‘Networkerror:Connectiontimedout’10.19‘Networkerror:Cannotassignrequestedaddress’

10.1‘Theserver'shostkeyisnotcachedintheregistry’ThiserrormessageoccurswhenPuTTYconnectstoanewSSHserver.Everyserveridentifiesitselfbymeansofahostkey;oncePuTTYknowsthehostkeyforaserver,itwillbeabletodetectifamaliciousattackerredirectsyourconnectiontoanothermachine.

Ifyouseethismessage,itmeansthatPuTTYhasnotseenthishostkeybefore,andhasnowayofknowingwhetheritiscorrectornot.Youshouldattempttoverifythehostkeybyothermeans,suchasaskingthemachine'sadministrator.

IfyouseethismessageandyouknowthatyourinstallationofPuTTYhasconnectedtothesameserverbefore,itmayhavebeenrecentlyupgradedtoSSHprotocolversion2.SSHprotocols1and2useseparatehostkeys,sowhenyoufirstuseSSH-2withaserveryouhaveonlyusedSSH-1withbefore,youwillseethismessageagain.Youshouldverifythecorrectnessofthekeyasbefore.

Seesection2.2formoreinformationonhostkeys.

10.2‘WARNING-POTENTIALSECURITYBREACH!’Thismessage,followedby‘Theserver'shostkeydoesnotmatchtheonePuTTYhascachedintheregistry’,meansthatPuTTYhasconnectedtotheSSHserverbefore,knowswhatitshostkeyshouldbe,buthasfoundadifferentone.

Thismaymeanthatamaliciousattackerhasreplacedyourserverwithadifferentone,orhasredirectedyournetworkconnectiontotheirownmachine.Ontheotherhand,itmaysimplymeanthattheadministratorofyourserverhasaccidentallychangedthekeywhileupgradingtheSSHsoftware;thisshouldn'thappenbutitisunfortunatelypossible.

Youshouldcontactyourserver'sadministratorandseewhethertheyexpectthehostkeytohavechanged.Ifso,verifythenewhostkeyinthesamewayasyouwouldifitwasnew.

Seesection2.2formoreinformationonhostkeys.

10.3‘SSHprotocolversion2requiredbyourconfigurationbutserveronlyprovides(old,insecure)SSH-1’Bydefault,PuTTYonlysupportsconnectingtoSSHserversthatimplementSSHprotocolversion2.Ifyouseethismessage,theserveryou'retryingtoconnecttoonlysupportstheolderSSH-1protocol.

IftheservergenuinelyonlysupportsSSH-1,thenyouneedtoeitherchangethe‘SSHprotocolversion’setting(seesection4.18.4),orusethe-1command-lineoption;inanycase,youshouldnottreattheresultingconnectionassecure.

YoumightstartseeingthismessagewithnewversionsofPuTTY(from0.68onwards)whereyoudidn'tbefore,becauseitusedtobepossibletoconfigurePuTTYtoautomaticallyfallbackfromSSH-2toSSH-1.Thisisnolongersupported,topreventthepossibilityofadowngradeattack.

10.4‘Thefirstciphersupportedbytheserveris...belowtheconfiguredwarningthreshold’ThisoccurswhentheSSHserverdoesnotofferanycipherswhichyouhaveconfiguredPuTTYtoconsiderstrongenough.Bydefault,PuTTYputsupthiswarningonlyforsingle-DESandArcfourencryption.

Seesection4.21formoreinformationonthismessage.

10.5‘Serversentdisconnectmessagetype2(protocolerror):"Toomanyauthenticationfailuresforroot"’ThismessageisproducedbyanOpenSSH(orSunSSH)serverifitreceivesmorefailedauthenticationattemptsthanitiswillingtotolerate.

ThiscaneasilyhappenifyouareusingPageantandhavealargenumberofkeysloadedintoit,sincetheseserverscounteachofferofapublickeyasanauthenticationattempt.Thiscanbeworkedaroundbyspecifyingthekeythat'srequiredfortheauthenticationinthePuTTYconfiguration(seesection4.22.8);PuTTYwillignoreanyotherkeysPageantmayhave,butwillaskPageanttodotheauthentication,sothatyoudon'thavetotypeyourpassphrase.

Ontheserver,thiscanbeworkedaroundbydisablingpublic-keyauthenticationor(forSunSSHonly)byincreasingMaxAuthTriesinsshd_config.

10.6‘Outofmemory’ThisoccurswhenPuTTYtriestoallocatemorememorythanthesystemcangiveit.Thismayhappenforgenuinereasons:ifthecomputerreallyhasrunoutofmemory,orifyouhaveconfiguredanextremelylargenumberoflinesofscrollbackinyourterminal.PuTTYisnotabletorecoverfromrunningoutofmemory;itwillterminateimmediatelyaftergivingthiserror.

However,thiserrorcanalsooccurwhenmemoryisnotrunningoutatall,becausePuTTYreceivesdatainthewrongformat.InSSH-2andalsoinSFTP,theserversendsthelengthofeachmessagebeforethemessageitself;soPuTTYwillreceivethelength,trytoallocatespaceforthemessage,andthenreceivetherestofthemessage.IfthelengthPuTTYreceivesisgarbage,itwilltrytoallocatearidiculousamountofmemory,andwillterminatewithan‘Outofmemory’error.

ThiscanhappeninSSH-2,ifPuTTYandtheserverhavenotenabledencryptioninthesameway(seequestionA.7.3intheFAQ).

ThiscanalsohappeninPSCPorPSFTP,ifyourloginscriptsontheservergenerateoutput:theclientprogramwillbeexpectinganSFTPmessagestartingwithalength,andifitreceivessometextfromyourloginscriptsinsteaditwilltrytointerpretthemasamessagelength.SeequestionA.7.4fordetailsofthis.

10.7‘Internalerror’,‘Internalfault’,‘Assertionfailed’Anyerrorbeginningwiththeword‘Internal’shouldneveroccur.Ifitdoes,thereisabuginPuTTYbydefinition;pleaseseeappendixBandreportittous.

Similarly,anyerrormessagestartingwith‘Assertionfailed’isabuginPuTTY.Pleasereportittous,andincludetheexacttextfromtheerrormessagebox.

10.8‘Unabletousethisprivatekeyfile’,‘Couldn'tloadprivatekey’,‘Keyisofwrongtype’VariousformsofthiserrorareprintedinthePuTTYwindow,orwrittentothePuTTYEventLog(seesection3.1.3.1)whentryingpublic-keyauthentication,orgivenbyPageantwhentryingtoloadaprivatekey.

Ifyouseeoneofthesemessages,itoftenindicatesthatyou'vetriedtoloadakeyofaninappropriatetypeintoPuTTY,Plink,PSCP,PSFTP,orPageant.

Youmayhavespecifiedakeythat'sinappropriatefortheconnectionyou'remaking.TheSSH-1andSSH-2protocolsrequiredifferentprivatekeyformats,andaSSH-1keycan'tbeusedforaSSH-2connection(orviceversa).

Alternatively,youmayhavetriedtoloadanSSH-2keyina‘foreign’format(OpenSSHorssh.com)directlyintooneofthePuTTYtools,inwhichcaseyouneedtoimportitintoPuTTY'snativeformat(*.PPK)usingPuTTYgen-seesection8.2.12.

10.9‘Serverrefusedourpublickey’or‘Keyrefused’VariousformsofthiserrorareprintedinthePuTTYwindow,orwrittentothePuTTYEventLog(seesection3.1.3.1)whentryingpublic-keyauthentication.

Ifyouseeoneofthesemessages,itmeansthatPuTTYhassentapublickeytotheserverandofferedtoauthenticatewithit,andtheserverhasrefusedtoacceptauthentication.Thisusuallymeansthattheserverisnotconfiguredtoacceptthiskeytoauthenticatethisuser.

ThisisalmostcertainlynotaproblemwithPuTTY.Ifyouseethistypeofmessage,thefirstthingyoushoulddoischeckyourserverconfigurationcarefully.Commonerrorsincludehavingthewrongpermissionsorownershipsetonthepublickeyortheuser'shomedirectoryontheserver.Also,readthePuTTYEventLog;theservermayhavesentdiagnosticmessagesexplainingexactlywhatproblemithadwithyoursetup.

Section8.3hassomehintsonserver-sidepublickeysetup.

10.10‘Accessdenied’,‘Authenticationrefused’VariousformsofthiserrorareprintedinthePuTTYwindow,orwrittentothePuTTYEventLog(seesection3.1.3.1)duringauthentication.

Ifyouseeoneofthesemessages,itmeansthattheserverhasrefusedalltheformsofauthenticationPuTTYhastriedandithasnofurtherideas.

ItmaybeworthcheckingtheEventLogfordiagnosticmessagesfromtheservergivingmoredetail.

ThiserrorcanbecausedbybuggySSH-1serversthatfailtocopewiththevariousstrategiesweuseforcamouflagingpasswordsintransit.Upgradeyourserver,orusetheworkaroundsdescribedinsection4.27.1andpossiblysection4.27.2.

10.11‘Nosupportedauthenticationmethodsavailable’ThiserrorindicatesthatPuTTYhasrunoutofwaystoauthenticateyoutoanSSHserver.ThismaybebecausePuTTYhasTISorkeyboard-interactiveauthenticationdisabled,inwhichcasesection4.22.4andsection4.22.5.

10.12‘IncorrectCRCreceivedonpacket’or‘IncorrectMACreceivedonpacket’ThiserroroccurswhenPuTTYdecryptsanSSHpacketanditschecksumisnotcorrect.Thisprobablymeanssomethinghasgonewrongintheencryptionordecryptionprocess.It'sdifficulttotellfromthiserrormessagewhethertheproblemisintheclient,intheserver,orinbetween.

Inparticular,ifthenetworkiscorruptingdataattheTCPlevel,itmayonlybeobviouswithcryptographicprotocolssuchasSSH,whichexplicitlychecktheintegrityofthetransferreddataandcomplainloudlyifthechecksfail.Corruptionofprotocolswithoutintegrityprotection(suchasHTTP)willmanifestinmoresubtlefailures(suchasmisdisplayedtextorimagesinawebbrowser)whichmaynotbenoticed.

Occasionallythishasbeencausedbyserverbugs.Anexampleisthebugdescribedatsection4.27.6,althoughyou'reveryunlikelytoencounterthatonethesedays.

InthiscontextMACstandsforMessageAuthenticationCode.It'sacryptographicterm,andithasnothingatalltodowithEthernetMAC(MediaAccessControl)addresses,orwiththeApplecomputer.

10.13‘Incomingpacketwasgarbledondecryption’ThiserroroccurswhenPuTTYdecryptsanSSHpacketandthedecrypteddatamakesnosense.Thisprobablymeanssomethinghasgonewrongintheencryptionordecryptionprocess.It'sdifficulttotellfromthiserrormessagewhethertheproblemisintheclient,intheserver,orinbetween.

Ifyougetthiserror,onethingyoucouldtrywouldbetofiddlewiththesettingof‘MiscomputesSSH-2encryptionkeys’(seesection4.27.7)or‘IgnoresSSH-2maximumpacketsize’(seesection4.27.11)ontheBugspanel.

10.14‘PuTTYX11proxy:variouserrors’ThisfamilyoferrorsarereportedwhenPuTTYisdoingXforwarding.TheyaresentbacktotheXapplicationrunningontheSSHserver,whichwillusuallyreporttheerrortotheuser.

WhenPuTTYenablesXforwarding(seesection3.4)itcreatesavirtualXdisplayrunningontheSSHserver.Thisdisplayrequiresauthenticationtoconnecttoit(thisishowPuTTYpreventsotherusersonyourservermachinefromconnectingthroughthePuTTYproxytoyourrealXdisplay).PuTTYalsosendstheserverthedetailsitneedstoenableclientstoconnect,andtheservershouldputthismechanisminplaceautomatically,soyourXapplicationsshouldjustwork.

AcommonreasonwhypeopleseeoneofthesemessagesisbecausetheyusedSSHtologinasoneuser(let'ssay‘fred’),andthenusedtheUnixsucommandtobecomeanotheruser(typically‘root’).Theoriginaluser,‘fred’,hasaccesstotheXauthenticationdataprovidedbytheSSHserver,andcanrunXapplicationswhichareforwardedovertheSSHconnection.However,theseconduser(‘root’)doesnotautomaticallyhavetheauthenticationdatapassedontoit,soattemptingtorunanXapplicationasthatuseroftenfailswiththiserror.

Ifthishappens,itisnotaproblemwithPuTTY.YouneedtoarrangeforyourXauthenticationdatatobepassedfromtheuseryouloggedinastotheuseryouusedsutobecome.Howyoudothisdependsonyourparticularsystem;infactmanymodernversionsofsudoitautomatically.

10.15‘Networkerror:Softwarecausedconnectionabort’ThisisagenericerrorproducedbytheWindowsnetworkcodewhenitkillsanestablishedconnectionforsomereason.Forexample,itmighthappenifyoupullthenetworkcableoutofthebackofanEthernet-connectedcomputer,orifWindowshasanyothersimilarreasontobelievetheentirenetworkhasbecomeunreachable.

Windowsalsogeneratesthiserrorifithasgivenuponthemachineattheotherendoftheconnectioneverrespondingtoit.Ifthenetworkbetweenyourclientandservergoesdownandyourclientthentriestosendsomedata,Windowswillmakeseveralattemptstosendthedataandwillthengiveupandkilltheconnection.Inparticular,thiscanoccurevenifyoudidn'ttypeanything,ifyouareusingSSH-2andPuTTYattemptsakeyre-exchange.(Seesection4.19.2formoreaboutkeyre-exchange.)

(Itcanalsooccurifyouareusingkeepalivesinyourconnection.Otherpeoplehavereportedthatkeepalivesfixthiserrorforthem.Seesection4.13.1foradiscussionoftheprosandconsofkeepalives.)

WearenotawareofanyreasonwhythiserrormightoccurthatwouldrepresentabuginPuTTY.Theproblemisbetweenyou,yourWindowssystem,yournetworkandtheremotesystem.

10.16‘Networkerror:Connectionresetbypeer’Thiserroroccurswhenthemachinesateachendofanetworkconnectionlosetrackofthestateoftheconnectionbetweenthem.Forexample,youmightseeitifyourSSHservercrashes,andmanagestorebootfullybeforeyounextattempttosenddatatoit.

However,themostcommonreasontoseethismessageisifyouareconnectingthroughafirewalloraNATrouterwhichhastimedtheconnectionout.SeequestionA.7.8intheFAQformoredetails.Youmaybeabletoimprovethesituationbyusingkeepalives;seesection4.13.1fordetailsonthis.

NotethatWindowscanproducethiserrorinsomecircumstanceswithoutseeingaconnectionresetfromtheserver,forinstanceiftheconnectiontothenetworkislost.

10.17‘Networkerror:Connectionrefused’ThiserrormeansthatthenetworkconnectionPuTTYtriedtomaketoyourserverwasrejectedbytheserver.UsuallythishappensbecausetheserverdoesnotprovidetheservicewhichPuTTYistryingtoaccess.

Checkthatyouareconnectingwiththecorrectprotocol(SSH,TelnetorRlogin),andcheckthattheportnumberiscorrect.Ifthatfails,consulttheadministratorofyourserver.

10.18‘Networkerror:Connectiontimedout’ThiserrormeansthatthenetworkconnectionPuTTYtriedtomaketoyourserverreceivednoresponseatallfromtheserver.Usuallythishappensbecausetheservermachineiscompletelyisolatedfromthenetwork,orbecauseitisturnedoff.

CheckthatyouhavecorrectlyenteredthehostnameorIPaddressofyourservermachine.Ifthatfails,consulttheadministratorofyourserver.

Unixalsogeneratesthiserrorwhenittriestosenddatadownaconnectionandcontactwiththeserverhasbeencompletelylostduringaconnection.(ThereisadelayofminutesbeforeUnixgivesuponreceivingareplyfromtheserver.)ThiscanoccurifyoutypethingsintoPuTTYwhilethenetworkisdown,butitcanalsooccurifPuTTYdecidesofitsownaccordtosenddata:duetoarepeatkeyexchangeinSSH-2(seesection4.19.2)orduetokeepalives(section4.13.1).

10.19‘Networkerror:Cannotassignrequestedaddress’ThismeansthattheoperatingsystemrejectedtheparametersofthenetworkconnectionPuTTYtriedtomake,usuallywithoutactuallytryingtoconnecttoanything,becausetheyweresimplyinvalid.

Acommonwaytoprovokethiserroristoaccidentallytrytoconnecttoport0,whichisnotavalidportnumber.

AppendixA:PuTTYFAQThisFAQispublishedonthePuTTYwebsite,andalsoprovidedasanappendixinthemanual.

A.1IntroductionA.1.1WhatisPuTTY?

A.2FeaturessupportedinPuTTYA.2.1DoesPuTTYsupportSSH-2?A.2.2DoesPuTTYsupportreadingOpenSSHorssh.comSSH-2privatekeyfiles?A.2.3DoesPuTTYsupportSSH-1?A.2.4DoesPuTTYsupportlocalecho?A.2.5DoesPuTTYsupportstoringsettings,soIdon'thavetochangethemeverytime?A.2.6DoesPuTTYsupportstoringitssettingsinadiskfile?A.2.7DoesPuTTYsupportfull-screenmode,likeaDOSbox?A.2.8DoesPuTTYhavetheabilitytoremembermypasswordsoIdon'thavetotypeiteverytime?A.2.9Isthereanoptiontoturnofftheannoyinghostkeyprompts?A.2.10WillyouwriteanSSHserverforthePuTTYsuite,togowiththeclient?A.2.11CanPSCPorPSFTPtransferfilesinASCIImode?

A.3PortstootheroperatingsystemsA.3.1WhatportsofPuTTYexist?A.3.2IsthereaporttoUnix?A.3.3What'sthepointoftheUnixport?UnixhasOpenSSH.A.3.4WilltherebeaporttoWindowsCEorPocketPC?A.3.5IsthereaporttoWindows3.1?A.3.6WilltherebeaporttotheMac?A.3.7WilltherebeaporttoEPOC?A.3.8WilltherebeaporttotheiPhone?

A.4EmbeddingPuTTYinotherprogramsA.4.1IstheSSHorTelnetcodeavailableasaDLL?A.4.2IstheSSHorTelnetcodeavailableasaVisualBasiccomponent?A.4.3HowcanIusePuTTYtomakeanSSHconnectionfrom

withinanotherprogram?A.5DetailsofPuTTY'soperation

A.5.1WhatterminaltypedoesPuTTYuse?A.5.2WheredoesPuTTYstoreitsdata?

A.6HOWTOquestionsA.6.1Whatloginname/passwordshouldIuse?A.6.2WhatcommandscanItypeintomyPuTTYterminalwindow?A.6.3HowcanImakePuTTYstartupmaximised?A.6.4HowcanIcreateaWindowsshortcuttostartaparticularsavedsessiondirectly?A.6.5HowcanIstartanSSHsessionstraightfromthecommandline?A.6.6HowdoIcopyandpastebetweenPuTTYandotherWindowsapplications?A.6.7HowdoIuseallPuTTY'sfeatures(publickeys,proxying,cipherselection,etc.)inPSCP,PSFTPandPlink?A.6.8HowdoIusePSCP.EXE?WhenIdouble-clickitgivesmeacommandpromptwindowwhichthenclosesinstantly.A.6.9HowdoIusePSCPtocopyafilewhosenamehasspacesin?A.6.10ShouldIrunthe32-bitorthe64-bitversion?

A.7TroubleshootingA.7.1WhydoIsee‘Fatal:Protocolerror:Expectedcontrolrecord’inPSCP?A.7.2IclickedonacolourintheColourspanel,andthecolourdidn'tchangeinmyterminal.A.7.3AftertryingtoestablishanSSH-2connection,PuTTYsays‘Outofmemory’anddies.A.7.4Whenattemptingafiletransfer,eitherPSCPorPSFTPsays‘Outofmemory’anddies.A.7.5PSFTPtransfersfilesmuchslowerthanPSCP.A.7.6WhenIrunfull-colourapplications,Iseeareasofblackspacewherecolouroughttobe,orviceversa.A.7.7WhenIchangesometerminalsettings,nothinghappens.A.7.8MyPuTTYsessionsunexpectedlycloseaftertheyareidleforawhile.A.7.9PuTTY'snetworkconnectionstimeouttooquicklywhennetworkconnectivityistemporarilylost.

A.7.10WhenIcatabinaryfile,Iget‘PuTTYPuTTYPuTTY’onmycommandline.A.7.11WhenIcatabinaryfile,mywindowtitlechangestoanonsensestring.A.7.12MykeyboardstopsworkingoncePuTTYdisplaysthepasswordprompt.A.7.13Oneormorefunctionkeysdon'tdowhatIexpectedinaserver-sideapplication.A.7.14WhydoIsee‘Couldn'tloadprivatekeyfrom...’?WhycanPuTTYgenloadmykeybutnotPuTTY?A.7.15WhenI'mconnectedtoaRedHatLinux8.0system,somecharactersdon'tdisplayproperly.A.7.16SinceIupgradedtoPuTTY0.54,thescrollbackhasstoppedworkingwhenIrunscreen.A.7.17SinceIupgradedWindowsXPtoServicePack2,Ican'tuseaddresseslike127.0.0.2.A.7.18PSFTPcommandsseemtobemissingadirectoryseparator(slash).A.7.19Doyouwanttohearabout‘Softwarecausedconnectionabort’?A.7.20MySSH-2sessionlocksupforafewsecondseverysooften.A.7.21PuTTYfailstostartup.Windowsclaimsthat‘theapplicationconfigurationisincorrect’.A.7.22WhenIput32-bitPuTTYinC:\WINDOWS\SYSTEM32onmy64-bitWindowssystem,‘DuplicateSession’doesn'twork.

A.8SecurityquestionsA.8.1IsitsafeformetodownloadPuTTYanduseitonapublicPC?A.8.2WhatdoesPuTTYleaveonasystem?HowcanIcleanupafterit?A.8.3HowcomePuTTYnowsupportsDSA,whenthewebsiteusedtosayhowinsecureitwas?A.8.4Couldn'tPageantuseVirtualLock()tostopprivatekeysbeingwrittentodisk?

A.9AdministrativequestionsA.9.1Wouldyoulikemetoregisteryouanicerdomainname?A.9.2WouldyoulikefreewebhostingforthePuTTYwebsite?A.9.3WouldyoulinktomywebsitefromthePuTTYwebsite?

A.9.4Whydon'tyoumovePuTTYtoSourceForge?A.9.5Whycan'tIsubscribetotheputty-bugsmailinglist?A.9.6Ifputty-bugsisn'tageneral-subscriptionmailinglist,whatis?A.9.7HowcanIdonatetoPuTTYdevelopment?A.9.8CanIhavepermissiontoputPuTTYonacoverdisk/distributeitwithothersoftware/etc?A.9.9CanyousignanagreementindemnifyingusagainstsecurityproblemsinPuTTY?A.9.10Canyousignthisformgrantinguspermissiontouse/distributePuTTY?A.9.11CanyouwriteusaformalnoticeofpermissiontousePuTTY?A.9.12Canyousignanythingforus?A.9.13Ifyouwon'tsignanything,canyougiveussomesortofassurancethatyouwon'tmakePuTTYclosed-sourceinfuture?A.9.14Canyouprovideuswithexportcontrolinformation/FIPScertificationforPuTTY?A.9.15Asoneofourexistingsoftwarevendors,canyoujustfillinthisquestionnaireforus?A.9.16Thesha1sums/sha256sums/etcfilesonyourdownloadpagedon'tmatchthebinaries.

A.10MiscellaneousquestionsA.10.1IsPuTTYaportofOpenSSH,orbasedonOpenSSHorOpenSSL?A.10.2WherecanIbuysillyputty?A.10.3Whatdoes‘PuTTY’mean?A.10.4HowdoIpronounce‘PuTTY’?

A.1IntroductionA.1.1WhatisPuTTY?

A.1.1WhatisPuTTY?PuTTYisaclientprogramfortheSSH,TelnetandRloginnetworkprotocols.

Theseprotocolsareallusedtorunaremotesessiononacomputer,overanetwork.PuTTYimplementstheclientendofthatsession:theendatwhichthesessionisdisplayed,ratherthantheendatwhichitruns.

Inreallysimpleterms:yourunPuTTYonaWindowsmachine,andtellittoconnectto(forexample)aUnixmachine.PuTTYopensawindow.Then,anythingyoutypeintothatwindowissentstraighttotheUnixmachine,andeverythingtheUnixmachinesendsbackisdisplayedinthewindow.SoyoucanworkontheUnixmachineasifyouweresittingatitsconsole,whileactuallysittingsomewhereelse.

A.2FeaturessupportedinPuTTYIngeneral,ifyouwanttoknowifPuTTYsupportsaparticularfeature,youshouldlookforitonthePuTTYwebsite.Inparticular:

trythechangespage,andseeifyoucanfindthefeatureonthere.Ifafeatureislistedthere,it'sbeenimplemented.Ifit'slistedasachangemadesincethelatestversion,itshouldbeavailableinthedevelopmentsnapshots,inwhichcasetestingwillbeverywelcome.trytheWishlistpage,andseeifyoucanfindthefeaturethere.Ifit'sonthere,andnotinthe‘Recentlyfixed’section,itprobablyhasn'tbeenimplemented.

A.2.1DoesPuTTYsupportSSH-2?A.2.2DoesPuTTYsupportreadingOpenSSHorssh.comSSH-2privatekeyfiles?A.2.3DoesPuTTYsupportSSH-1?A.2.4DoesPuTTYsupportlocalecho?A.2.5DoesPuTTYsupportstoringsettings,soIdon'thavetochangethemeverytime?A.2.6DoesPuTTYsupportstoringitssettingsinadiskfile?A.2.7DoesPuTTYsupportfull-screenmode,likeaDOSbox?A.2.8DoesPuTTYhavetheabilitytoremembermypasswordsoIdon'thavetotypeiteverytime?A.2.9Isthereanoptiontoturnofftheannoyinghostkeyprompts?A.2.10WillyouwriteanSSHserverforthePuTTYsuite,togowiththeclient?A.2.11CanPSCPorPSFTPtransferfilesinASCIImode?

A.2.1DoesPuTTYsupportSSH-2?Yes.SSH-2supporthasbeenavailableinPuTTYsinceversion0.50.

Publickeyauthentication(bothRSAandDSA)inSSH-2isnewinversion0.52.

A.2.2DoesPuTTYsupportreadingOpenSSHorssh.comSSH-2privatekeyfiles?PuTTYdoesn'tsupportthisnatively(seethewishlistentryforreasonswhynot),butasof0.53PuTTYgencanconvertbothOpenSSHandssh.comprivatekeyfilesintoPuTTY'sformat.

A.2.3DoesPuTTYsupportSSH-1?Yes.SSH-1supporthasalwaysbeenavailableinPuTTY.

However,theSSH-1protocolhasmanyweaknessesandisnolongerconsideredsecure;youshoulduseSSH-2insteadifatallpossible.

Asof0.68,PuTTYwillnolongerfallbacktoSSH-1iftheserverdoesn'tappeartosupportSSH-2;youmustexplicitlyaskforSSH-1.

A.2.4DoesPuTTYsupportlocalecho?Yes.Version0.52haspropersupportforlocalecho.

Inversion0.51andbefore,localechocouldnotbeseparatedfromlocallineediting(whereyoutypealineoftextlocally,anditisnotsenttotheserveruntilyoupressReturn,soyouhavethechancetoedititandcorrectmistakesbeforetheserverseesit).Newinversion0.52,localechoandlocallineeditingareseparateoptions,andbydefaultPuTTYwilltrytodetermineautomaticallywhethertoenablethemornot,basedonwhichprotocolyouhaveselectedandalsobasedonhintsfromtheserver.IfyouhaveaproblemwithPuTTY'sdefaultchoice,youcanforceeachoptiontobeenabledordisabledasyouchoose.ThecontrolsareintheTerminalpanel,inthesectionmarked‘Linedisciplineoptions’.

A.2.5DoesPuTTYsupportstoringsettings,soIdon'thavetochangethemeverytime?Yes,allofPuTTY'ssettingscanbesavedinnamedsessionprofiles.Youcanalsochangethedefaultsettingsthatareusedfornewsessions.Seesection4.1.2inthedocumentationforhowtodothis.

A.2.6DoesPuTTYsupportstoringitssettingsinadiskfile?Notatpresent,althoughsection4.29inthedocumentationgivesamethodofachievingthesameeffect.

A.2.7DoesPuTTYsupportfull-screenmode,likeaDOSbox?Yes;thisisanewfeatureinversion0.52.

A.2.8DoesPuTTYhavetheabilitytoremembermypasswordsoIdon'thavetotypeiteverytime?No,itdoesn't.

Rememberingyourpasswordisabadplanforobvioussecurityreasons:anyonewhogainsaccesstoyourmachinewhileyou'reawayfromyourdeskcanfindouttherememberedpassword,anduseit,abuseitorchangeit.

Inaddition,it'snotevenpossibleforPuTTYtoautomaticallysendyourpasswordinaTelnetsession,becauseTelnetdoesn'tgivetheclientsoftwareanyindicationofwhichpartoftheloginprocessisthepasswordprompt.PuTTYwouldhavetoguess,bylookingforwordslike‘password’inthesessiondata;andifyourloginprogramiswritteninsomethingotherthanEnglish,thiswon'twork.

InSSH,rememberingyourpasswordwouldbepossibleintheory,buttheredoesn'tseemtobemuchpointsinceSSHsupportspublickeyauthentication,whichismoreflexibleandmoresecure.Seechapter8inthedocumentationforafulldiscussionofpublickeyauthentication.

A.2.9Isthereanoptiontoturnofftheannoyinghostkeyprompts?No,thereisn't.Andtherewon'tbe.Evenifyouwriteityourselfandsendusthepatch,wewon'tacceptit.

ThoseannoyinghostkeypromptsarethewholepointofSSH.Withoutthem,allthecryptographictechnologySSHusestosecureyoursessionisdoingnothingmorethanmakinganattacker'sjobslightlyharder;insteadofsittingbetweenyouandtheserverwithapacketsniffer,theattackermustactuallysubvertarouterandstartmodifyingthepacketsgoingbackandforth.Butthat'snotallthatmuchharderthanjustsniffing;andwithouthostkeychecking,itwillgocompletelyundetectedbyclientorserver.

Hostkeycheckingisyourguaranteethattheencryptionyouputonyourdataattheclientendisthesameencryptiontakenoffthedataattheserverend;it'syourguaranteethatithasn'tbeenremovedandreplacedsomewhereontheway.Hostkeycheckingmakestheattacker'sjobastronomicallyhard,comparedtopacketsniffing,andevencomparedtosubvertingarouter.InsteadofapplyingalittleintelligenceandkeepinganeyeonBugtraq,theattackermustnowperformabrute-forceattackagainstatleastonemilitary-strengthcipher.Thatinsignificanthostkeypromptreallydoesmakethatmuchdifference.

Ifyou'rehavingaspecificproblemwithhostkeychecking-perhapsyouwantanautomatedbatchjobtomakeuseofPSCPorPlink,andtheinteractivehostkeypromptishangingthebatchprocess-thentherightwaytofixitistoaddthecorrecthostkeytotheRegistryinadvance,oriftheRegistryisnotavailable,tousethe-hostkeycommand-lineoption.Thatway,youretaintheimportantfeatureofhostkeychecking:therightkeywillbeacceptedandthewrongoneswillnot.Addinganoptiontoturnhostkeycheckingoffcompletelyisthewrongsolutionandwewillnotdoit.

Ifyouhavehostkeysavailableinthecommonknown_hostsformat,wehaveascriptcalledkh2reg.pytoconvertthemtoaWindows.REGfile,whichcanbeinstalledaheadoftimebydouble-clickingorusingREGEDIT.

A.2.10WillyouwriteanSSHserverforthePuTTYsuite,togowiththeclient?No.Theonlyreasonwemightwanttowouldbeifwecouldeasilyre-useexistingcodeandsignificantlycutdowntheeffort.Wedon'tbelievethisisthecase;therejustisn'tenoughcommongroundbetweenanSSHclientandservertomakeitworthwhile.

IfsomeoneelsewantstousebitsofPuTTYintheprocessofwritingaWindowsSSHserver,they'dbeperfectlywelcometoofcourse,butIreallycan'tseeitbeingalotlesseffortforustodothatthanitwouldbeforustowriteaserverfromthegroundup.Wedon'thavetime,andwedon'thavemotivation.Thecodeisavailableifanyoneelsewantstotryit.

A.2.11CanPSCPorPSFTPtransferfilesinASCIImode?Unfortunatelynot.

Untilrecently,thiswasalimitationofthefiletransferprotocols:theSCPandSFTPprotocolshadnonotionoftransferringafileinanythingotherthanbinarymode.(ThisisstilltrueofSCP.)

ThecurrentdraftprotocolspecofSFTPproposesameansofimplementingASCIItransfer.AtsomepointPSCP/PSFTPmayimplementthisproposal.

A.3PortstootheroperatingsystemsTheeventualgoalisforPuTTYtobeamulti-platformprogram,abletorunonatleastWindows,MacOSandUnix.

PortingwillbecomeeasieroncePuTTYhasageneralisedportinglayer,drawingaclearlinebetweenplatform-dependentandplatform-independentcode.Thegeneralintentionwasforthisportinglayertoevolvenaturallyaspartoftheprocessofdoingthefirstport;aUnixporthasnowbeenreleasedandtheplanseemstobeworkingsofar.

A.3.1WhatportsofPuTTYexist?A.3.2IsthereaporttoUnix?A.3.3What'sthepointoftheUnixport?UnixhasOpenSSH.A.3.4WilltherebeaporttoWindowsCEorPocketPC?A.3.5IsthereaporttoWindows3.1?A.3.6WilltherebeaporttotheMac?A.3.7WilltherebeaporttoEPOC?A.3.8WilltherebeaporttotheiPhone?

A.3.1WhatportsofPuTTYexist?Currently,releaseversionsofPuTTYtoolsonlyrunonWindowssystemsandUnix.

Asof0.68,thesuppliedPuTTYexecutablesrunonversionsofWindowsfromXPonwards,uptoandincludingWindows10;andweknowofnoreasonwhyPuTTYshouldnotcontinuetoworkonfutureversionsofWindows.Weprovide32-bitand64-bitWindowsexecutables;seequestionA.6.10fordiscussionofthecompatibilityissuesaroundthat.

(WeusedtoalsoprovideexecutablesforWindowsfortheAlphaprocessor,butstoppedafter0.58duetolackofinterest.)

Inthedevelopmentcode,apartialporttoMacOSexists(seequestionA.3.6).

CurrentlyPuTTYdoesnotrunonWindowsCE(seequestionA.3.4).

Wedonothaverelease-qualityportsforanyothersystemsatthepresenttime.IfanyonetoldyouwehadanAndroidport,oraniOSport,oranyotherportofPuTTY,theyweremistaken.Wedon't.

Therearesomethird-partyportstovariousplatforms,mentionedontheLinkspageofourwebsite.

A.3.2IsthereaporttoUnix?Asof0.54,thereareUnixportsofmostofthetraditionalPuTTYtools,andalsooneentirelynewapplication.

Ifyoulookatthesourcerelease,youshouldfindaunixsubdirectory.Thereareacoupleofwaysofbuildingit,includingtheusualconfigure/make;seethefileREADMEinthesourcedistribution.ThisshouldbuildyouUnixportsofPlink,PuTTYitself,PuTTYgen,PSCP,PSFTP,Pageant,andalsopterm-anxterm-typeprogramwhichsupportsthesameterminalemulationasPuTTY.

Ifyoudon'thaveGtk,youshouldstillbeabletobuildthecommand-linetools.

A.3.3What'sthepointoftheUnixport?UnixhasOpenSSH.Allsortsoflittlethings.ptermisdirectlyusefultoanyonewhoprefersPuTTY'sterminalemulationtoxterm's,whichatleastsomepeopledo.UnixPlinkhasapparentlyfoundanicheamongpeoplewhofindthecomplexityofOpenSSLmakesOpenSSHhardtoinstall(andwhodon'tmindPlinknothavingasmanyfeatures).SomeuserswanttogeneratealargenumberofSSHkeysonUnixandthencopythemallintoPuTTY,andtheUnixPuTTYgenshouldallowthemtoautomatethatconversionprocess.

Thereweredevelopmentadvantagesaswell;portingPuTTYtoUnixwasavaluablepath-findingeffortforotherfutureports,andalsoallowedustousetheexcellentLinuxtoolValgrindtohelpwithdebugging,whichhasalreadyimprovedPuTTY'sstabilityonallplatforms.

However,ifyou'reaUnixuserandyoucanseenoreasontoswitchfromOpenSSHtoPuTTY/Plink,thenyou'reprobablyright.Wedon'texpectourUnixporttobetherightthingforeverybody.

A.3.4WilltherebeaporttoWindowsCEorPocketPC?Weoncedidsomeworkonsuchaport,butitonlyreachedanearlystage,andcertainlynotausefulone.It'snolongerbeingactivelyworkedon.

A.3.5IsthereaporttoWindows3.1?PuTTYisa32-bitapplicationfromthegroundup,soitwon'trunonWindows3.1asanative16-bitprogram;anditwouldbeveryhardtoportittodoso,becauseofWindows3.1'svilememoryallocationmechanisms.

However,itispossibleintheorytocompiletheexistingPuTTYsourceinsuchawaythatitwillrununderWin32s(anextensiontoWindows3.1toletyourun32-bitprograms).Inordertodothisyou'llneedtherightkindofCcompiler-modernversionsofVisualCatleasthavestoppedbeingbackwardscompatibletoWin32s.Also,thelasttimewetriedthisitdidn'tworkverywell.

A.3.6WilltherebeaporttotheMac?Wehopeso!

Weattemptedonearound2005,writtenasanativeCocoaapplication,butitturnedouttobeveryslowtoredrawitswindowforsomereasonwenevergottothebottomof.

In2015,afterportingtheGTKfrontendtoworkwithGTK3,webegananotherattemptbasedonmakingsmallchangestotheGTKcodeandbuildingitagainsttheOSXQuartzversionofGTK3.Thisdoesn'tseemtohavethewindowredrawingproblemanymore,soit'salreadygotfurtherthanthelasteffort,butitisstillsubstantiallyunfinished.

IfanyOSXand/orGTKprogrammingexpertsarekeentohaveafinishedversionofthis,weurgethemtohelpoutwithsomeoftheremainingproblems!

A.3.7WilltherebeaporttoEPOC?Ihopeso,butgiventhatportsaren'treallyprogressingveryfastevenonsystemsthedevelopersdoalreadyknowhowtoprogramfor,itmightbealongtimebeforeanyofusgetroundtolearninganewsystemanddoingtheportforthat.

However,someoftheworkhasbeendonebyotherpeople;seetheLinkspageofourwebsiteforvariousthird-partyports.

A.3.8WilltherebeaporttotheiPhone?Wehavenoplanstowritesuchaportourselves;noneofushasaniPhone,anddevelopingandpublishingapplicationsforitlooksawkwardandexpensive.

However,thereisathird-partySSHclientfortheiPhoneandiPodTouchcalledpTerm,whichisapparentlybasedonPuTTY.(Thisisnothingtodowithoursimilarly-namedpterm,whichisastandaloneterminalemulatorforUnixsystems;seequestionA.3.2.)

A.4EmbeddingPuTTYinotherprogramsA.4.1IstheSSHorTelnetcodeavailableasaDLL?A.4.2IstheSSHorTelnetcodeavailableasaVisualBasiccomponent?A.4.3HowcanIusePuTTYtomakeanSSHconnectionfromwithinanotherprogram?

A.4.1IstheSSHorTelnetcodeavailableasaDLL?No,itisn't.Itwouldtakeareasonableamountofrewritingforthistobepossible,andsincethePuTTYprojectitselfdoesn'tbelieveinDLLs(theymakeinstallationmoreerror-prone)noneofushastakenthetimetodoit.

Mostofthecodecleanupworkwouldbeagoodthingtohappeningeneral,soifanyonefeelslikehelping,wewouldn'tsayno.

Seealsothewishlistentry.

A.4.2IstheSSHorTelnetcodeavailableasaVisualBasiccomponent?No,itisn't.NoneofthePuTTYteamusesVisualBasic,andnoneofushasanyparticularneedtomakeSSHconnectionsfromaVisualBasicapplication.Inaddition,allthepreliminaryworktoturnitintoaDLLwouldbenecessaryfirst;andfurthermore,wedon'tevenknowhowtowriteVBcomponents.

Ifsomeoneofferstodosomeofthisworkforus,wemightconsiderit,butunlessthathappensIcan'tseeVBintegrationbeinganywhereotherthantheverybottomofourprioritylist.

A.4.3HowcanIusePuTTYtomakeanSSHconnectionfromwithinanotherprogram?ProbablyyourbestbetistousePlink,thecommand-lineconnectiontool.IfyoucanstartPlinkasasecondWindowsprocess,andarrangeforyourprimaryprocesstobeabletosenddatatothePlinkprocess,andreceivedatafromit,throughpipes,thenyoushouldbeabletomakeSSHconnectionsfromyourprogram.

ThisiswhatCVSforWindowsdoes,forexample.

A.5DetailsofPuTTY'soperationA.5.1WhatterminaltypedoesPuTTYuse?A.5.2WheredoesPuTTYstoreitsdata?

A.5.1WhatterminaltypedoesPuTTYuse?Formostpurposes,PuTTYcanbeconsideredtobeanxtermterminal.

PuTTYalsosupportssometerminalcontrolsequencesnotsupportedbytherealxterm:notablytheLinuxconsolesequencesthatreconfigurethecolourpalette,andthetitlebarcontrolsequencesusedbyDECterm(whicharedifferentfromthextermones;PuTTYsupportsboth).

Bydefault,PuTTYannouncesitsterminaltypetotheserverasxterm.Ifyouhaveaproblemwiththis,youcanreconfigureittosaysomethingelse;vt220mighthelpifyouhavetrouble.

A.5.2WheredoesPuTTYstoreitsdata?OnWindows,PuTTYstoresmostofitsdata(savedsessions,SSHhostkeys)intheRegistry.Thepreciselocationis

HKEY_CURRENT_USER\Software\SimonTatham\PuTTY

andwithinthatarea,savedsessionsarestoredunderSessionswhilehostkeysarestoredunderSshHostKeys.

PuTTYalsorequiresarandomnumberseedfile,toimprovetheunpredictabilityofrandomlychosendataneededaspartoftheSSHcryptography.ThisisstoredbydefaultinafilecalledPUTTY.RND;thisisstoredbydefaultinthe‘ApplicationData’directory,orfailingthat,oneofanumberoffallbacklocations.Ifyouwanttochangethelocationoftherandomnumberseedfile,youcanputyourchosenpathnameintheRegistry,at

HKEY_CURRENT_USER\Software\SimonTatham\PuTTY\RandSeedFile

YoucanaskPuTTYtodeleteallthisdata;seequestionA.8.2.

OnUnix,PuTTYstoresallofthisdatainadirectory~/.puttybydefault.

A.6HOWTOquestionsA.6.1Whatloginname/passwordshouldIuse?A.6.2WhatcommandscanItypeintomyPuTTYterminalwindow?A.6.3HowcanImakePuTTYstartupmaximised?A.6.4HowcanIcreateaWindowsshortcuttostartaparticularsavedsessiondirectly?A.6.5HowcanIstartanSSHsessionstraightfromthecommandline?A.6.6HowdoIcopyandpastebetweenPuTTYandotherWindowsapplications?A.6.7HowdoIuseallPuTTY'sfeatures(publickeys,proxying,cipherselection,etc.)inPSCP,PSFTPandPlink?A.6.8HowdoIusePSCP.EXE?WhenIdouble-clickitgivesmeacommandpromptwindowwhichthenclosesinstantly.A.6.9HowdoIusePSCPtocopyafilewhosenamehasspacesin?A.6.10ShouldIrunthe32-bitorthe64-bitversion?

A.6.1Whatloginname/passwordshouldIuse?Thisisnotaquestionyoushouldbeaskingus.

PuTTYisacommunicationstool,formakingconnectionstoothercomputers.Wemaintainthetool;wedon'tadministeranycomputersthatyou'relikelytobeabletouse,inthesamewaythatthepeoplewhomakewebbrowsersaren'tresponsibleformostofthecontentyoucanviewinthem.Wecannothelpwithquestionsofthissort.

Ifyouknowthenameofthecomputeryouwanttoconnectto,butdon'tknowwhatloginnameorpasswordtouse,youshouldtalktowhoeveradministersthatcomputer.Ifyoudon'tknowwhothatis,seethenextquestionforsomepossiblewaystofindout.

A.6.2WhatcommandscanItypeintomyPuTTYterminalwindow?Again,thisisnotaquestionyoushouldbeaskingus.Youneedtoreadthemanuals,orasktheadministrator,ofthecomputeryouhaveconnectedto.

PuTTYdoesnotprocessthecommandsyoutypeintoit.It'sonlyacommunicationstool.Itmakesaconnectiontoanothercomputer;itpassesthecommandsyoutypetothatothercomputer;anditpassestheothercomputer'sresponsesbacktoyou.Therefore,thepreciserangeofcommandsyoucanusewillnotdependonPuTTY,butonwhatkindofcomputeryouhaveconnectedtoandwhatsoftwareisrunningonit.ThePuTTYteamcannothelpyouwiththat.

(ThinkofPuTTYasbeingabitlikeatelephone.Ifyouphonesomebodyupandyoudon'tknowwhatlanguagetospeaktomakethemunderstandyou,itisn'tthetelephonecompany'sjobtofindthatoutforyou.Wejustprovidethemeansforyoutogetintouch;makingyourselfunderstoodissomebodyelse'sproblem.)

Ifyouareunsureofwheretostartlookingfortheadministratorofyourserver,agoodplacetostartmightbetorememberhowyoufoundoutthehostnameinthePuTTYconfiguration.Ifyouweregiventhathostnamebye-mail,forexample,youcouldtryaskingthepersonwhosentyouthate-mail.Ifyourcompany'sITdepartmentprovidedyouwithready-madePuTTYsavedsessions,thenthatITdepartmentcanprobablyalsotellyousomethingaboutwhatcommandsyoucantypeduringthosesessions.ButthePuTTYmaintainerteamdoesnotadministeranyserveryouarelikelytobeconnectingto,andcannothelpyouwithquestionsofthistype.

A.6.3HowcanImakePuTTYstartupmaximised?CreateaWindowsshortcuttostartPuTTYfrom,andsetitas‘RunMaximized’.

A.6.4HowcanIcreateaWindowsshortcuttostartaparticularsavedsessiondirectly?TorunaPuTTYsessionsavedunderthename‘mysession’,createaWindowsshortcutthatinvokesPuTTYwithacommandlinelike

\path\name\to\putty.exe-load"mysession"

(Note:priorto0.53,thesyntaxwas@session.Thisisnowdeprecatedandmayberemovedatsomepoint.)

A.6.5HowcanIstartanSSHsessionstraightfromthecommandline?Usethecommandlineputty-sshhost.name.Alternatively,createasavedsessionthatspecifiestheSSHprotocol,andstartthesavedsessionasshowninquestionA.6.4.

A.6.6HowdoIcopyandpastebetweenPuTTYandotherWindowsapplications?CopyandpasteworkssimilarlytotheXWindowSystem.YouusetheleftmousebuttontoselecttextinthePuTTYwindow.Theactofselectionautomaticallycopiesthetexttotheclipboard:thereisnoneedtopressCtrl-InsorCtrl-Coranythingelse.Infact,pressingCtrl-CwillsendaCtrl-Ccharactertotheotherendofyourconnection(justlikeitdoestherestofthetime),whichmayhaveunpleasanteffects.Theonlythingyouneedtodo,tocopytexttotheclipboard,istoselectit.

TopastetheclipboardcontentsintoaPuTTYwindow,bydefaultyouclicktherightmousebutton.Ifyouhaveathree-buttonmouseandareusedtoXapplications,youcanconfigurepastingtobedonebythemiddlebuttoninstead,butthisisnotthedefaultbecausemostWindowsusersdon'thaveamiddlebuttonatall.

YoucanalsopastebypressingShift-Ins.

A.6.7HowdoIuseallPuTTY'sfeatures(publickeys,proxying,cipherselection,etc.)inPSCP,PSFTPandPlink?Mostmajorfeatures(e.g.,publickeys,portforwarding)areavailablethroughcommandlineoptions.Seethedocumentation.

Notallfeaturesareaccessiblefromthecommandlineyet,althoughwe'dliketofixthis.Inthemeantime,youcanusemostofPuTTY'sfeaturesifyoucreateaPuTTYsavedsession,andthenusethenameofthesavedsessiononthecommandlineinplaceofahostname.ThisworksforPSCP,PSFTPandPlink(butdon'texpectportforwardinginthefiletransferapplications!).

A.6.8HowdoIusePSCP.EXE?WhenIdouble-clickitgivesmeacommandpromptwindowwhichthenclosesinstantly.PSCPisacommand-lineapplication,notaGUIapplication.Ifyourunitwithoutarguments,itwillsimplyprintahelpmessageandterminate.

TousePSCPproperly,runitfromaCommandPromptwindow.Seechapter5inthedocumentationformoredetails.

A.6.9HowdoIusePSCPtocopyafilewhosenamehasspacesin?IfPSCPisusingthetraditionalSCPprotocol,thisisconfusing.Ifyou'respecifyingafileatthelocalend,youjustuseonesetofquotesasyouwouldnormallydo:

pscp"localfilenamewithspaces"user@host:

pscpuser@host:myfile"localfilenamewithspaces"

Butifthefilenameyou'respecifyingisontheremoteside,youhavetousebackslashesandtwosetsofquotes:

pscpuser@host:"\"remotefilenamewithspaces\""local_filename

pscplocal_filenameuser@host:"\"remotefilenamewithspaces\""

Worsestill,inaremote-to-localcopyyouhavetospecifythelocalfilenameexplicitly,otherwisePSCPwillcomplainthattheydon'tmatch(unlessyouspecifiedthe-unsafeoption).Thefollowingcommandwillgiveanerrormessage:

c:\>pscpuser@host:"\"ooer\"".

warning:remotehosttriedtowritetoafilecalled'ooer'

whenwerequestedafilecalled'"ooer"'.

Instead,youneedtospecifythelocalfilenameinfull:

c:\>pscpuser@host:"\"ooer\"""ooer"

IfPSCPisusingthenewerSFTPprotocol,noneofthisisaproblem,andallfilenameswithspacesinarespecifiedusingasinglepairofquotesintheobviousway:

pscp"localfile"user@host:

pscpuser@host:"remotefile".

A.6.10ShouldIrunthe32-bitorthe64-bitversion?Ifyou'renotsure,the32-bitversionisgenerallythesafeoption.ItwillrunperfectlywellonallprocessorsandonallversionsofWindowsthatPuTTYsupports.PuTTYdoesn'trequiretorunasa64-bitapplicationtoworkwell,andhavinga32-bitPuTTYona64-bitsystemisn'tlikelytocauseyouanytrouble.

The64-bitversion(firstreleasedin0.68)willonlyrunifyouhavea64-bitprocessoranda64-biteditionofWindows(bothofthesethingsarelikelytobetrueofanyrecentWindowsPC).Itwillrunsomewhatfaster(inparticular,thecryptographywillbefaster,especiallyduringlinksetup),butitwillconsumeslightlymorememory.

IfyouneedtouseanexternalDLLforGSSAPIauthentication,thatDLLmayonlybeavailableina32-bitor64-bitform,andthatwilldictatetheversionofPuTTYyouneedtouse.(Youwillprobablyknowifyou'redoingthis;seesection4.23.2inthedocumentation.)

A.7TroubleshootingA.7.1WhydoIsee‘Fatal:Protocolerror:Expectedcontrolrecord’inPSCP?A.7.2IclickedonacolourintheColourspanel,andthecolourdidn'tchangeinmyterminal.A.7.3AftertryingtoestablishanSSH-2connection,PuTTYsays‘Outofmemory’anddies.A.7.4Whenattemptingafiletransfer,eitherPSCPorPSFTPsays‘Outofmemory’anddies.A.7.5PSFTPtransfersfilesmuchslowerthanPSCP.A.7.6WhenIrunfull-colourapplications,Iseeareasofblackspacewherecolouroughttobe,orviceversa.A.7.7WhenIchangesometerminalsettings,nothinghappens.A.7.8MyPuTTYsessionsunexpectedlycloseaftertheyareidleforawhile.A.7.9PuTTY'snetworkconnectionstimeouttooquicklywhennetworkconnectivityistemporarilylost.A.7.10WhenIcatabinaryfile,Iget‘PuTTYPuTTYPuTTY’onmycommandline.A.7.11WhenIcatabinaryfile,mywindowtitlechangestoanonsensestring.A.7.12MykeyboardstopsworkingoncePuTTYdisplaysthepasswordprompt.A.7.13Oneormorefunctionkeysdon'tdowhatIexpectedinaserver-sideapplication.A.7.14WhydoIsee‘Couldn'tloadprivatekeyfrom...’?WhycanPuTTYgenloadmykeybutnotPuTTY?A.7.15WhenI'mconnectedtoaRedHatLinux8.0system,somecharactersdon'tdisplayproperly.A.7.16SinceIupgradedtoPuTTY0.54,thescrollbackhasstoppedworkingwhenIrunscreen.A.7.17SinceIupgradedWindowsXPtoServicePack2,Ican'tuseaddresseslike127.0.0.2.A.7.18PSFTPcommandsseemtobemissingadirectoryseparator(slash).A.7.19Doyouwanttohearabout‘Softwarecausedconnectionabort’?

A.7.20MySSH-2sessionlocksupforafewsecondseverysooften.A.7.21PuTTYfailstostartup.Windowsclaimsthat‘theapplicationconfigurationisincorrect’.A.7.22WhenIput32-bitPuTTYinC:\WINDOWS\SYSTEM32onmy64-bitWindowssystem,‘DuplicateSession’doesn'twork.

A.7.1WhydoIsee‘Fatal:Protocolerror:Expectedcontrolrecord’inPSCP?ThishappensbecausePSCPwasexpectingtoseedatafromtheserverthatwaspartofthePSCPprotocolexchange,andinsteaditsawdatathatitcouldn'tmakeanysenseofatall.

Thisalmostalwayshappensbecausethestartupscriptsinyouraccountontheservermachinearegeneratingoutput.ThisisimpossibleforPSCP,oranyotherSCPclient,toworkaround.Youshouldneverusestartupfiles(.bashrc,.cshrcandsoon)whichgenerateoutputinnon-interactivesessions.

ThisisnotactuallyaPuTTYproblem.IfPSCPfailsinthisway,thenallotherSCPclientsarelikelytofailinexactlythesameway.Theproblemisattheserverend.

A.7.2IclickedonacolourintheColourspanel,andthecolourdidn'tchangeinmyterminal.Thatisn'thowyou'resupposedtousetheColourspanel.

Duringthecourseofasession,PuTTYpotentiallyusesallthecolourslistedintheColourspanel.It'snotaquestionofusingonlyoneofthemandyouchoosingwhichone;PuTTYwillusethemall.ThepurposeoftheColourspanelistoletyouadjusttheappearanceofallthecolours.Sotochangethecolourofthecursor,forexample,youwouldselect‘CursorColour’,pressthe‘Modify’button,andselectanewcolourfromthedialogboxthatappeared.Similarly,ifyouwantyoursessiontoappearingreen,youshouldselect‘DefaultForeground’andpress‘Modify’.Clickingon‘ANSIGreen’won'tturnyoursessiongreen;itwillonlyallowyoutoadjusttheshadeofgreenusedwhenPuTTYisinstructedbytheservertodisplaygreentext.

A.7.3AftertryingtoestablishanSSH-2connection,PuTTYsays‘Outofmemory’anddies.Ifthishappensjustwhiletheconnectionisstartingup,thisoftenindicatesthatforsomereasontheclientandserverhavefailedtoestablishasessionencryptionkey.Somehow,theyhaveperformedcalculationsthatshouldhavegiveneachofthemthesamekey,buthaveendedupwithdifferentkeys;sodataencryptedbyoneanddecryptedbytheotherlookslikerandomgarbage.

Thiscausesan‘outofmemory’errorbecausethefirstencrypteddataPuTTYexpectstoseeisthelengthofanSSHmessage.Normallythiswillbesomethingwellunder100bytes.Ifthedecryptionhasfailed,PuTTYwillseeacompletelyrandomlengthintheregionoftwogigabytes,andwilltrytoallocateenoughmemorytostorethisnon-existentmessage.Thiswillimmediatelyleadtoitthinkingitdoesn'thaveenoughmemory,andpanicking.

Ifthishappenstoyou,itisquitelikelytostillbeaPuTTYbugandyoushouldreportit(althoughitmightbeabuginyourSSHserverinstead);butitdoesn'tnecessarilymeanyou'veactuallyrunoutofmemory.

A.7.4Whenattemptingafiletransfer,eitherPSCPorPSFTPsays‘Outofmemory’anddies.Thisisalmostalwayscausedbyyourloginscriptsontheservergeneratingoutput.PSCPorPSFTPwillreceivethatoutputwhentheywereexpectingtoseethestartofafiletransferprotocol,andtheywillattempttointerprettheoutputasfile-transferprotocol.Thiswillusuallyleadtoan‘outofmemory’errorformuchthesamereasonsasgiveninquestionA.7.3.

Thisisasetupprobleminyouraccountonyourserver,notaPSCP/PSFTPbug.Yourloginscriptsshouldnevergenerateoutputduringnon-interactivesessions;securefiletransferisnottheonlyformofremoteaccessthatwillbreakiftheydo.

OnUnix,asimplefixistoensurethatallthepartsofyourloginscriptthatmightgenerateoutputarein.profile(ifyouuseaBourneshellderivative)or.login(ifyouuseaCshell).Puttingtheminmoregeneralfilessuchas.bashrcor.cshrcisliabletoleadtoproblems.

A.7.5PSFTPtransfersfilesmuchslowerthanPSCP.ThethroughputofPSFTP0.54shouldbemuchbetterthan0.53bandprior;we'veaddedcodetotheSFTPbackendtoqueueseveralblocksofdataratherthanwaitingforanacknowledgementforeach.(TheSCPbackenddidnotsufferfromthisperformanceissuebecauseSCPisamuchsimplerprotocol.)

A.7.6WhenIrunfull-colourapplications,Iseeareasofblackspacewherecolouroughttobe,orviceversa.Youalmostcertainlyneedtochangethe‘Usebackgroundcolourtoerasescreen’settingintheTerminalpanel.Ifthereistoomuchblackspace(thecommonersituation),youshouldenableit,whileifthereistoomuchcolour,youshoulddisableit.(Seesection4.3.5.)

InoldversionsofPuTTY,thiswasdisabledbydefault,andwouldnottakeeffectuntilyouresettheterminal(seequestionA.7.7).Since0.54,itisenabledbydefault,andchangestakeeffectimmediately.

A.7.7WhenIchangesometerminalsettings,nothinghappens.Someoftheterminaloptions(notablyAutoWrapandbackground-colourscreenerase)actuallyrepresentthedefaultsetting,ratherthanthecurrentlyactivesetting.Theservercansendsequencesthatmodifytheseoptionsinmid-session,butwhentheterminalisreset(byserveraction,orbyyouchoosing‘ResetTerminal’fromtheSystemmenu)thedefaultsarerestored.

Inversions0.53bandprior,ifyouchangeoneoftheseoptionsinthemiddleofasession,youwillfindthatthechangedoesnotimmediatelytakeeffect.Itwillonlytakeeffectonceyouresettheterminal.

Inversion0.54,thebehaviourhaschanged-changestothesesettingstakeeffectimmediately.

A.7.8MyPuTTYsessionsunexpectedlycloseaftertheyareidleforawhile.Sometypesoffirewall,andalmostanyrouterdoingNetworkAddressTranslation(NAT,alsoknownasIPmasquerading),willforgetaboutaconnectionthroughthemiftheconnectiondoesnothingfortoolong.Thiswillcausetheconnectiontoberudelycutoffwhencontactisresumed.

YoucantrytocombatthisbytellingPuTTYtosendkeepalives:packetsofdatawhichhavenoeffectontheactualsession,butwhichreassuretherouterorfirewallthatthenetworkconnectionisstillactiveandworthrememberingabout.

Keepalivesdon'tsolveeverything,unfortunately;althoughtheycausegreaterrobustnessagainstthissortofrouter,theycanalsocausealossofrobustnessagainstnetworkdropouts.Seesection4.13.1inthedocumentationformorediscussionofthis.

A.7.9PuTTY'snetworkconnectionstimeouttooquicklywhennetworkconnectivityistemporarilylost.ThisisaWindowsproblem,notaPuTTYproblem.Thetimeoutvaluecan'tbesetonperapplicationorpersessionbasis.ToincreasetheTCPtimeoutglobally,youneedtotinkerwiththeRegistry.

OnWindows95,98orME,theregistrykeyyouneedtocreateorchangeis

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\VxD\

MSTCP\MaxDataRetries

(itmustbeoftypeDWORDinWin95,orStringinWin98/ME).(SeeMSKnowledgeBasearticle158474formoreinformation.)

OnWindowsNT,2000,orXP,theregistrykeytocreateorchangeis

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\

Parameters\TcpMaxDataRetransmissions

anditmustbeoftypeDWORD.(SeeMSKnowledgeBasearticles120642and314053formoreinformation.)

Setthekey'svaluetosomethinglike10.ThiswillcauseWindowstotryhardertokeepconnectionsaliveinsteadofabandoningthem.

A.7.10WhenIcatabinaryfile,Iget‘PuTTYPuTTYPuTTY’onmycommandline.Don'tdothat,then.

Thisisdesignedbehaviour;whenPuTTYreceivesthecharacterControl-Efromtheremoteserver,itinterpretsitasarequesttoidentifyitself,andsoitsendsbackthestring‘PuTTY’asifthatstringhadbeenenteredatthekeyboard.Control-Eshouldonlybesentbyprogramsthatarepreparedtodealwiththeresponse.WritingabinaryfiletoyourterminalislikelytooutputmanyControl-Echaracters,andcausethisbehaviour.Don'tdoit.It'sabadplan.

Tomitigatetheeffects,youcouldconfiguretheanswerbackstringtobeempty(seesection4.3.7);butwritingbinaryfilestoyourterminalislikelytocausevariousotherunpleasantbehaviour,sothisisonlyasmallremedy.

A.7.11WhenIcatabinaryfile,mywindowtitlechangestoanonsensestring.Don'tdothat,then.

ItisdesignedbehaviourthatPuTTYshouldhavetheabilitytoadjustthewindowtitleoninstructionsfromtheserver.Normallythecontrolsequencethatdoesthisshouldonlybesentdeliberately,byprogramsthatknowwhattheyaredoingandintendtoputmeaningfultextinthewindowtitle.Writingabinaryfiletoyourterminalrunstheriskofsendingthesamecontrolsequencebyaccident,andcauseunexpectedchangesinthewindowtitle.Don'tdoit.

A.7.12MykeyboardstopsworkingoncePuTTYdisplaysthepasswordprompt.No,itdoesn't.PuTTYjustdoesn'tdisplaythepasswordyoutype,sothatsomeonelookingatyourscreencan'tseewhatitis.

UnliketheWindowsloginprompts,PuTTYdoesn'tdisplaythepasswordasarowofasteriskseither.Thisissothatsomeonelookingatyourscreencan'teventellhowlongyourpasswordis,whichmightbevaluableinformation.

A.7.13Oneormorefunctionkeysdon'tdowhatIexpectedinaserver-sideapplication.Ifyou'vealreadytriedalltherelevantoptionsinthePuTTYKeyboardpanel,youmayneedtomailthePuTTYmaintainersandask.

Itisnotusuallyhelpfuljusttotelluswhichapplication,whichserveroperatingsystem,andwhichkeyisn'tworking;inordertoreplicatetheproblemwewouldneedtohaveacopyofeveryoperatingsystem,andeveryapplication,thatanyonehasevercomplainedabout.

PuTTYrespondstofunctionkeypressesbysendingasequenceofcontrolcharacterstotheserver.Ifafunctionkeyisn'tdoingwhatyouexpect,it'slikelythatthecharactersequenceyourapplicationisexpectingtoreceiveisnotthesameastheonePuTTYissending.Thereforewhatwereallyneedtoknowiswhatsequencetheapplicationisexpecting.

Thesimplestwaytoinvestigatethisistofindsomeotherterminalenvironment,inwhichthatfunctionkeydoeswork;andtheninvestigatewhatsequencethefunctionkeyissendinginthatsituation.OnereasonablyeasywaytodothisonaUnixsystemistotypethecommandcat,andthenpressthefunctionkey.Thisislikelytoproduceoutputoftheform^[[11~.YoucanalsodothisinPuTTY,tofindoutwhatsequencethefunctionkeyisproducinginthat.ThenyoucanmailthePuTTYmaintainersandtellus‘IwantedtheF1keytosend^[[11~,butinsteadit'ssending^[OP,canthisbedone?’,orsomethingsimilar.

YoushouldstillreadtheFeedbackpageonthePuTTYwebsite(alsoprovidedasappendixBinthemanual),andfollowtheguidelinescontainedinthat.

A.7.14WhydoIsee‘Couldn'tloadprivatekeyfrom...’?WhycanPuTTYgenloadmykeybutnotPuTTY?It'slikelythatyou'vegeneratedanSSHprotocol2keywithPuTTYgen,butyou'retryingtouseitinanSSH-1connection.SSH-1andSSH-2keyshavedifferentformats,and(atleastin0.52)PuTTY'sreportingofakeyinthewrongformatisn'toptimal.

ToconnectusingSSH-2toaserverthatsupportsbothversions,youneedtochangetheconfigurationfromthedefault(seequestionA.2.1).

A.7.15WhenI'mconnectedtoaRedHatLinux8.0system,somecharactersdon'tdisplayproperly.Acommoncomplaintisthathyphensinmanpagesshowupasa-acute.

Withrelease8.0,RedHatappeartohavemadeUTF-8thedefaultcharacterset.ThereappearstobenowayforterminalemulatorssuchasPuTTYtoknowthis(asfarasweknow,theappropriateescapesequencetoswitchintoUTF-8modeisn'tsent).

AfixistoconfiguresessionstoRH8systemstouseUTF-8translation-seesection4.10.1inthedocumentation.(Notethatifyouuse‘ChangeSettings’,changesmaynottakeplaceimmediately-seequestionA.7.7.)

Ifyoureallywanttochangethecharactersetusedbytheserver,therightplaceis/etc/sysconfig/i18n,butthisshouldn'tbenecessary.

A.7.16SinceIupgradedtoPuTTY0.54,thescrollbackhasstoppedworkingwhenIrunscreen.PuTTY'sterminalemulatorhasalwayshadthepolicythatwhenthe‘alternatescreen’isinuse,nothingisaddedtothescrollback.Thisisbecausetheusualsortsofprogramswhichusethealternatescreenarethingsliketexteditors,whichtendtoscrollbackandforthinthesamedocumentalot;so(a)theywouldfillupthescrollbackwithalargeamountofunhelpfullydisorderedtext,and(b)theycontaintheirownmethodfortheusertoscrollbacktothebittheywereinterestedin.WehavegenerallyfoundthispolicytodotheRightThinginalmostallsituations.

Unfortunately,screenisoneexception:itusesthealternatescreen,butit'sstillusuallyhelpfultohavePuTTY'sscrollbackcontinueworking.ThesimplestsolutionistogototheFeaturescontrolpanelandtick‘Disableswitchingtoalternateterminalscreen’.(Seesection4.6.4formoredetails.)Alternatively,youcantellscreenitselfnottousethealternatescreen:thescreenFAQsuggestsaddingtheline‘termcapinfoxtermti@:te@’toyour.screenrcfile.

Thereasonwhythisonlystartedtobeaproblemin0.54isbecausescreentypicallyusesanunusualcontrolsequencetoswitchtothealternatescreen,andpreviousversionsofPuTTYdidnotsupportthissequence.

A.7.17SinceIupgradedWindowsXPtoServicePack2,Ican'tuseaddresseslike127.0.0.2.SomepeoplewhoaskPuTTYtolistenonlocalhostaddressesotherthan127.0.0.1toforwardservicessuchasSMBandWindowsTerminalServiceshavefoundthatdoingsonolongerworkssincetheyupgradedtoWinXPSP2.

ThisisapparentlyanissuewithSP2thatisacknowledgedbyMicrosoftinMSKnowledgeBasearticle884020.Thearticlelinkstoafixyoucandownload.

(However,we'vebeentoldthatSP2alsofixesthebugthatmeansyouneedtousenon-127.0.0.1addressestoforwardTerminalServicesinthefirstplace.)

A.7.18PSFTPcommandsseemtobemissingadirectoryseparator(slash).SomepeoplehavereportedthefollowingincorrectbehaviourwithPSFTP:

psftp>pwd

Remotedirectoryis/dir1/dir2

psftp>getfilename.ext

/dir1/dir2filename.ext:nosuchfileordirectory

ThisisnotabuginPSFTP.ThereisaknownbuginsomeversionsofportableOpenSSH(bug697)thatcausesthesesymptoms;itappearstohavebeenintroducedaround3.7.x.Itmanifestsonlyoncertainplatforms(AIXiswhathasbeenreportedtous).

ThereisapatchforOpenSSHattachedtothatbug;it'salsofixedinrecentversionsofportableOpenSSH(fromaround3.8).

A.7.19Doyouwanttohearabout‘Softwarecausedconnectionabort’?InthedocumentationforPuTTY0.53and0.53b,wementionedthatwe'dliketohearaboutanyoccurrencesofthiserror.SincethereleaseofPuTTY0.54,however,we'vebeenconvincedthatthiserrordoesn'tindicatethatPuTTY'sdoinganythingwrong,andwedon'tneedtohearaboutfurtheroccurrences.Seesection10.15forourcurrentdocumentationofthiserror.

A.7.20MySSH-2sessionlocksupforafewsecondseverysooften.RecentversionsofPuTTYautomaticallyinitiaterepeatkeyexchangeonceperhour,toimprovesessionsecurity.Ifyourclientorservermachineisslow,youmayexperiencethisasadelayofanythinguptothirtysecondsorso.

Thesedelaysareinconvenient,buttheyarethereforyourprotection.Iftheyreallycauseyouaproblem,youcanchoosetoturnoffperiodicrekeyingusingthe‘Kex’configurationpanel(seesection4.19),butbeawarethatyouwillbesacrificingsecurityforthis.(FallingbacktoSSH-1wouldalsoremovethedelays,butwouldlosealotmoresecuritystill.Wedonotrecommendit.)

A.7.21PuTTYfailstostartup.Windowsclaimsthat‘theapplicationconfigurationisincorrect’.ThisiscausedbyabugincertainversionsofWindowsXPwhichistriggeredbyPuTTY0.58.Thiswasfixedin0.59.The‘xp-wont-run’entryinPuTTY'swishlisthasmoredetails.

A.7.22WhenIput32-bitPuTTYinC:\WINDOWS\SYSTEM32onmy64-bitWindowssystem,‘DuplicateSession’doesn'twork.TheshortanswerisnottoputthePuTTYexecutablesinthatlocation.

On64-bitsystems,C:\WINDOWS\SYSTEM32isintendedtocontainonly64-bitbinaries;Windows'32-bitbinariesliveinC:\WINDOWS\SYSWOW64.Whena32-bitPuTTYexecutablerunsona64-bitsystem,itcannotbydefaultseethe‘real’C:\WINDOWS\SYSTEM32atall,becausetheFileSystemRedirectorarrangesthattherunningprogramseestheappropriatekindofbinariesinSYSTEM32.Thus,operationsinthePuTTYsuitethatinvolveitaccessingitsownexecutables,suchas‘NewSession’and‘DuplicateSession’,willnotwork.

A.8SecurityquestionsA.8.1IsitsafeformetodownloadPuTTYanduseitonapublicPC?A.8.2WhatdoesPuTTYleaveonasystem?HowcanIcleanupafterit?A.8.3HowcomePuTTYnowsupportsDSA,whenthewebsiteusedtosayhowinsecureitwas?A.8.4Couldn'tPageantuseVirtualLock()tostopprivatekeysbeingwrittentodisk?

A.8.1IsitsafeformetodownloadPuTTYanduseitonapublicPC?ItdependsonwhetheryoutrustthatPC.Ifyoudon'ttrustthepublicPC,don'tusePuTTYonit,anddon'tuseanyothersoftwareyouplantotypepasswordsintoeither.Itmightbewatchingyourkeystrokes,oritmighttamperwiththePuTTYbinaryyoudownload.ThereisnoprogramsafeenoughthatyoucanrunitonanactivelymaliciousPCandgetawaywithtypingpasswordsintoit.

IfyoudotrustthePC,thenit'sprobablyOKtousePuTTYonit(butifyoudon'ttrustthenetwork,thenthePuTTYdownloadmightbetamperedwith,soitwouldbebettertocarryPuTTYwithyouonaUSBstick).

A.8.2WhatdoesPuTTYleaveonasystem?HowcanIcleanupafterit?PuTTYwillleavesomeRegistryentries,andarandomseedfile,onthePC(seequestionA.5.2).Windows7andupalsoremembersomeinformationaboutrecentlylaunchedsessionsforthe‘jumplist’feature.

IfyouareusingPuTTYonapublicPC,orsomebodyelse'sPC,youmightwanttocleanthisinformationupwhenyouleave.Youcandothatautomatically,byrunningthecommandputty-cleanup.Seesection3.8.2inthedocumentationformoredetail.(Notethatthisonlyremovessettingsforthecurrentlylogged-inuseronmulti-usersystems.)

IfPuTTYwasinstalledfromtheinstallerpackage,itwillalsoappearin‘Add/RemovePrograms’.Currentversionsoftheinstallerdonotoffertoremovetheabove-mentioneditems,soifyouwantthemremovedyoushouldrunputty-cleanupbeforeuninstalling.

A.8.3HowcomePuTTYnowsupportsDSA,whenthewebsiteusedtosayhowinsecureitwas?DSAhasamajorweaknessifbadlyimplemented:itreliesonarandomnumbergeneratortofartoogreatanextent.Iftherandomnumbergeneratorproducesanumberanattackercanpredict,theDSAprivatekeyisexposed-meaningthattheattackercanloginasyouonallsystemsthatacceptthatkey.

ThePuTTYpolicychangedbecausethedeveloperswereinformedofwaystoimplementDSAwhichdonotsuffernearlyasbadlyfromthisweakness,andindeedwhichdon'tneedtorelyonrandomnumbersatall.ForthisreasonwenowbelievePuTTY'sDSAimplementationisprobablyOK.

Therecentlyaddedelliptic-curvesignaturemethodsarealsoDSA-stylealgorithms,sotheyhavethissameweaknessinprinciple.OurECDSAimplementationusesthesamedefenceasDSA,whileourEd25519implementationusesthesimilarsystem(butdifferentindetails)thattheEd25519specmandates.

A.8.4Couldn'tPageantuseVirtualLock()tostopprivatekeysbeingwrittentodisk?Unfortunatelynot.TheVirtualLock()functionintheWindowsAPIdoesn'tdoaproperjob:itmaypreventsmallpiecesofaprocess'smemoryfrombeingpagedtodiskwhiletheprocessisrunning,butitdoesn'tstoptheprocess'smemoryasawholefrombeingswappedcompletelyouttodiskwhentheprocessislong-terminactive.AndPageantspendsmostofitstimeinactive.

A.9AdministrativequestionsA.9.1Wouldyoulikemetoregisteryouanicerdomainname?A.9.2WouldyoulikefreewebhostingforthePuTTYwebsite?A.9.3WouldyoulinktomywebsitefromthePuTTYwebsite?A.9.4Whydon'tyoumovePuTTYtoSourceForge?A.9.5Whycan'tIsubscribetotheputty-bugsmailinglist?A.9.6Ifputty-bugsisn'tageneral-subscriptionmailinglist,whatis?A.9.7HowcanIdonatetoPuTTYdevelopment?A.9.8CanIhavepermissiontoputPuTTYonacoverdisk/distributeitwithothersoftware/etc?A.9.9CanyousignanagreementindemnifyingusagainstsecurityproblemsinPuTTY?A.9.10Canyousignthisformgrantinguspermissiontouse/distributePuTTY?A.9.11CanyouwriteusaformalnoticeofpermissiontousePuTTY?A.9.12Canyousignanythingforus?A.9.13Ifyouwon'tsignanything,canyougiveussomesortofassurancethatyouwon'tmakePuTTYclosed-sourceinfuture?A.9.14Canyouprovideuswithexportcontrolinformation/FIPScertificationforPuTTY?A.9.15Asoneofourexistingsoftwarevendors,canyoujustfillinthisquestionnaireforus?A.9.16Thesha1sums/sha256sums/etcfilesonyourdownloadpagedon'tmatchthebinaries.

A.9.1Wouldyoulikemetoregisteryouanicerdomainname?No,thankyou.Evenifyoucanfindone(mostofthemseemtohavebeenregisteredalready,bypeoplewhodidn'taskwhetherweactuallywanteditbeforetheyapplied),we'rehappywiththePuTTYwebsitebeingexactlywhereitis.It'snothardtofind(justtype‘putty’intogoogle.comandwe'rethefirstlinkreturned),andwedon'tbelievetheadministrativehassleofmovingthesitewouldbeworththebenefit.

Inaddition,ifwedidwantacustomdomainname,wewouldwanttorunitourselves,soweknewforcertainthatitwouldcontinuetopointwherewewantedit,andwouldn'tsuddenlychangeordostrangethings.Havingitregisteredforusbyathirdpartywhowedon'tevenknowisnotthebestwaytoachievethis.

A.9.2WouldyoulikefreewebhostingforthePuTTYwebsite?Wealreadyhavesome,thanks.

A.9.3WouldyoulinktomywebsitefromthePuTTYwebsite?OnlyifthecontentofyourwebpageisofdefinitedirectinteresttoPuTTYusers.Ifyourcontentisunrelated,oronlytangentiallyrelated,toPuTTY,thenthelinkwouldsimplybeadvertisingforyou.

OneveryniceeffectoftheGooglerankingmechanismisthatbyandlarge,themostpopularwebsitesgetthehighestrankings.Thismeansthatwhenanordinarypersondoesasearch,thetopiteminthesearchisverylikelytobeahigh-qualitysiteorthesitetheyactuallywanted,ratherthanthesitewhichpaidthemostmoneyforitsranking.

ThePuTTYwebsiteisheldinhighesteembyGoogle,forpreciselythisreason:lotsofpeoplehavelinkedtoitsimplybecausetheylikePuTTY,withoutuseverhavingtoaskanyonetolinktous.Wefeelthatitwouldbeanabuseofthisesteemtouseittoboosttherankingofrandomadvertisers'websites.IfyouwantyourwebsitetohaveahighGoogleranking,we'dpreferthatyouachievethisthewaywedid-bybeinggoodenoughatwhatyoudothatpeoplewilllinktoyousimplybecausetheylikeyou.

Inparticular,wearen'tinterestedintradinglinksformoney(seeabove),andwecertainlyaren'tinterestedintradinglinksforotherlinks(sincewehavenoadvertisingonourwebsite,ourGooglerankingisnotevendirectlyworthanythingtous).Ifwedon'twanttolinktoyouforfree,thenweprobablywon'twanttolinktoyouatall.

IfyouhavesoftwarebasedonPuTTY,orspecificallydesignedtointeroperatewithPuTTY,orinsomeotherwayofgenuineinteresttoPuTTYusers,thenwewillprobablybehappytoaddalinktoyouonourLinkspage.Andifyou'rerunningaparticularlyvaluablemirrorofthePuTTYwebsite,wemightbeinterestedinlinkingtoyoufromourMirrorspage.

A.9.4Whydon'tyoumovePuTTYtoSourceForge?Partly,becausewedon'twanttomovethewebsitelocation(seequestionA.9.1).

Also,securityreasons.PuTTYisasecurityproduct,andassuchitisparticularlyimportanttoguardthecodeandthewebsiteagainstunauthorisedmodificationswhichmightintroducesubtlesecurityflaws.Therefore,wepreferthattheGitrepository,websiteandFTPsiteremainwheretheyare,underthedirectcontrolofsystemadministratorsweknowandtrustpersonally,ratherthanbeingrunbyalargeorganisationfullofpeoplewe'venevermetandwhichisknowntohavehadbreakinsinthepast.

NooffencetoSourceForge;Ithinktheydoawonderfuljob.Butthey'renotidealforeveryone,andinparticularthey'renotidealforus.

A.9.5Whycan'tIsubscribetotheputty-bugsmailinglist?Becauseyou'renotamemberofthePuTTYcoredevelopmentteam.Theputty-bugsmailinglistisnotageneralnewsgroup-likediscussionforum;it'sacontactaddressforthecoredevelopers,andaninternalmailinglistforustodiscussthingsamongourselves.Ifweopeneditupforeverybodytosubscribeto,itwouldturnintosomethingmorelikeanewsgroupandwewouldbecompletelyoverwhelmedbythevolumeoftraffic.It'shardenoughtokeepupwiththelistasitis.

A.9.6Ifputty-bugsisn'tageneral-subscriptionmailinglist,whatis?Thereisn'tone,thatweknowof.

IfsomeoneelsewantstosetupamailinglistorotherforumforPuTTYuserstohelpeachotherwithcommonproblems,thatwouldbefinewithus,thoughthePuTTYteamwouldalmostcertainlynothavethetimetoreadit.It'sprobablybettertouseoneoftheestablishednewsgroupsforthispurpose(seesectionB.1.2).

A.9.7HowcanIdonatetoPuTTYdevelopment?Please,pleasedon'tfeelyouhaveto.PuTTYiscompletelyfreesoftware,andnotshareware.Wethinkit'sveryimportantthateverybodywhowantstousePuTTYshouldbeableto,whethertheyhaveanymoneyornot;sothelastthingwewouldwantisforaPuTTYusertofeelguiltybecausetheyhaven'tpaidusanymoney.Ifyouwanttokeepyourmoney,pleasedokeepit.Wewouldn'tdreamofaskingforany.

Havingsaidallthat,ifyoustillreallywanttogiveusmoney,wewon'targue:-)Theeasiestwayforustoacceptdonationsisifyousendmoneyto<anakin@pobox.com>usingPayPal(www.paypal.com).Ifyoudon'tlikePayPal,talktous;wecanprobablyarrangesomealternativemeans.

Smalldonations(tensofdollarsortensofeuros)willprobablybespentonbeerorcurry,whichhelpsmotivateourvolunteerteamtocontinuedoingthisfortheworld.Largerdonationswillbespentonsomethingthatactuallyhelpsdevelopment,ifwecanfindanything(perhapsnewhardware,oracopyofWindowsXP),butifwecan'tfindanythingthenwe'lljustdistributethemoneyamongthedevelopers.Ifyouwanttobesureyourdonationisgoingtowardssomethingworthwhile,askusfirst.Ifyoudon'tliketheseterms,feelperfectlyfreenottodonate.Wedon'tmind.

A.9.8CanIhavepermissiontoputPuTTYonacoverdisk/distributeitwithothersoftware/etc?Yes.Formostthings,youneednotbotheraskingusexplicitlyforpermission;ourlicencealreadygrantsyoupermission.

SeesectionB.8formoredetails.

A.9.9CanyousignanagreementindemnifyingusagainstsecurityproblemsinPuTTY?No!

Avendorofphysicalsecurityproducts(e.g.locks)mightplausiblybewillingtoacceptfinancialliabilityforaproductthatfailedtoperformasadvertisedandresultedindamage(e.g.valuablesbeingstolen).Thereasontheycanaffordtodothisisbecausetheysellalotofunits,andonlyasmallproportionofthemwillfail;sotheycanmeettheirfinancialliabilityoutoftheincomefromalltherestoftheirsales,andstillhaveenoughleftovertomakeaprofit.Financialliabilityisintrinsicallylinkedtosellingyourproductformoney.

TherearetworeasonswhyPuTTYisnotanalogoustoaphysicallockinthiscontext.Oneisthatsoftwareproductsdon'texhibitrandomvariation:ifPuTTYhasasecurityhole(whichdoeshappen,althoughwedoourutmosttopreventitandtorespondquicklywhenitdoes),everycopyofPuTTYwillhavethesamehole,soit'slikelytoaffectalltheusersatthesametime.SoevenifouruserswereallpayingustousePuTTY,wewouldn'tbeabletosimultaneouslypayeveryaffectedusercompensationinexcessoftheamounttheyhadpaidusinthefirstplace.Itjustwouldn'twork.

Thesecond,muchmoreimportant,reasonisthatPuTTYusersdon'tpayus.ThePuTTYteamdoesnothaveanincome;it'savolunteereffortcomposedofpeoplespendingtheirsparetimetotrytowriteusefulsoftware.Wearen'tevenacompanyoranykindoflegallyrecognisedorganisation.We'rejustabunchofpeoplewhohappentodosomestuffinoursparetime.

Therefore,toaskustoassumefinancialliabilityistoaskustoassumeariskofhavingtopayitoutofourownpersonalpockets:outofthesamebudgetfromwhichwebuyfoodandclothesandpayourrent.That'smorethanwe'rewillingtogive.We'realreadygivingalotofoursparetimetodevelopingsoftwareforfree;ifwehadtopayourownmoneytodoitaswell,we'dstarttowonderwhywewerebothering.

Freesoftwarefundamentallydoesnotworkonthebasisoffinancialguarantees.Yourguaranteeofthesoftwarefunctioningcorrectlyissimplythatyouhavethesourcecodeandcancheckitbeforeyouuseit.Ifyouwanttobesuretherearen'tanysecurityholes,doasecurityauditofthePuTTYcode,orhireasecurityengineerifyoudon'thavethenecessaryskillsyourself:insteadoftryingtoensureyoucangetcompensationintheeventofadisaster,trytoensurethereisn'tadisasterinthefirstplace.

Ifyoureallywantfinancialsecurity,seeifyoucanfindasecurityengineerwhowilltakefinancialresponsibilityforthecorrectnessoftheirreview.(Thismightbelesslikelytosufferfromtheeverything-failing-at-onceproblemmentionedabove,becausesuchanengineerwouldprobablybereviewingalotofdifferentproductswhichwouldtendtofailindependently.)Failingthat,seeifyoucanpersuadeaninsurancecompanytoinsureyouagainstsecurityincidents,andiftheinsurerdemandsitasaconditionthengetourcodereviewedbyasecurityengineerthey'rehappywith.

A.9.10Canyousignthisformgrantinguspermissiontouse/distributePuTTY?Ifyourformcontainsanyclausealongthelinesof‘theundersignedrepresentsandwarrants’,we'renotgoingtosignit.ThisisparticularlytrueifitasksustowarrantthatPuTTYissecure;seequestionA.9.9formorediscussionofthis.Butitdoesn'treallymatterwhatwe'resupposedtobewarranting:evenifit'ssomethingwealreadybelieveistrue,suchasthatwedon'tinfringeanythird-partycopyright,wewillnotsignadocumentacceptinganylegalorfinancialliability.ThisissimplybecausethePuTTYdevelopmentprojecthasnoincomeoutofwhichtosatisfythatliability,orpaylegalcosts,shoulditbecomenecessary.Wecannotaffordtobesued.Weareassuringyouthatwehavedoneourbest;ifthatisn'tgoodenoughforyou,tough.

TheexistingPuTTYlicencedocumentalreadygivesyoupermissiontouseordistributePuTTYinprettymuchanywaywhichdoesnotinvolvepretendingyouwroteitorsuingusifitgoeswrong.Wethinkthatreallyoughttobeenoughforanybody.

SeealsoquestionA.9.12foranotherreasonwhywedon'twanttodothissortofthing.

A.9.11CanyouwriteusaformalnoticeofpermissiontousePuTTY?Wecould,inprinciple,butitisn'tclearwhatuseitwouldbe.Ifyouthinkthere'saseriouschanceofoneofthePuTTYcopyrightholderssuingyou(whichwedon't!),youwouldpresumablywantasignednoticefromallofthem;andwecouldn'tprovidethatevenifwewantedto,becausemanyofthecopyrightholdersarepeoplewhocontributedsomecodeinthepastandwithwhomwesubsequentlylostcontact.Thereforethebestwewouldbeabletodoevenintheorywouldbetohavethecoredevelopmentteamsignthedocument,whichwouldn'tguaranteeyouthatsomeothercopyrightholdermightnotsue.

SeealsoquestionA.9.12foranotherreasonwhywedon'twanttodothissortofthing.

A.9.12Canyousignanythingforus?Notunlessthere'sanincrediblygoodreason.

WearegenerallyunwillingtosetaprecedentthatinvolvesushavingtoenterintoindividualagreementswithPuTTYusers.Weestimatethatwehaveliterallymillionsofusers,andweabsolutelywouldnothavetimetogoroundsigningspecificagreementswitheveryoneofthem.Soifyouwantustosignsomethingspecificforyou,youmightusefullystoptoconsiderwhetherthere'sanythingspecialthatdistinguishesyoufrom999,999otherusers,andthereforeanyreasonweshouldbewillingtosignsomethingforyouwithoutitsettingsuchaprecedent.

Ifyourcompanypolicyrequiresyoutohaveanindividualagreementwiththesupplierofanysoftwareyouuse,thenyourcompanypolicyissimplynotwellsuitedtousingpopularfreesoftware,andweurgeyoutoconsiderthisasaflawinyourpolicy.

A.9.13Ifyouwon'tsignanything,canyougiveussomesortofassurancethatyouwon'tmakePuTTYclosed-sourceinfuture?Yesandno.

IfwhatyouwantisanassurancethatsomecurrentversionofPuTTYwhichyou'vealreadydownloadedwillremainfree,thenyoualreadyhavethatassurance:it'scalledthePuTTYLicence.Itgrantsyoupermissiontouse,distributeandcopythesoftwaretowhichitapplies;oncewe'vegrantedthatpermission(whichwehave),wecan'tjustrevokeit.

Ontheotherhand,ifyouwantanassurancethatfutureversionsofPuTTYwon'tbeclosed-source,that'smoredifficult.Wecouldinprinciplesignadocumentstatingthatwewouldneverreleaseaclosed-sourcePuTTY,butthatwouldn'tassureyouthatwewouldkeepreleasingopen-sourcePuTTYs:wewouldstillhavetheoptionofceasingtodevelopPuTTYatall,whichwouldsurelybeevenworseforyouthanmakingitclosed-source!(Andwealmostcertainlywouldn'twanttosignadocumentguaranteeingthatwewouldactuallycontinuetododevelopmentworkonPuTTY;wecertainlywouldn'tsignitforfree.Documentslikethatarecalledcontractsofemployment,andaregenerallynotsignedexceptinreturnforasizeablesalary.)

IfweweretostopdevelopingPuTTY,ortodecidetomakeallfuturereleasesclosed-source,thenyouwouldstillbefreetocopythelastopenreleaseinaccordancewiththecurrentlicence,andinparticularyoucouldstartyourownforkoftheprojectfromthatrelease.Ifthishappened,Iconfidentlypredictthatsomebodywoulddothat,andthatsomekindofafreePuTTYwouldcontinuetobedeveloped.There'salreadyprecedentforthatsortofthinghappeninginfreesoftware.Wecan'tguaranteethatsomebodyotherthanyouwoulddoit,ofcourse;youmighthavetodoityourself.Butwecanassureyouthattherewouldbenothingpreventinganyonefromcontinuingfreedevelopmentifwestopped.

(Finally,wecanalsoconfidentlypredictthatifwemadePuTTYclosed-sourceandsomeonemadeanopen-sourcefork,mostpeoplewould

switchtothelatter.Therefore,itwouldbeprettystupidofustotryit.)

A.9.14Canyouprovideuswithexportcontrolinformation/FIPScertificationforPuTTY?SomepeoplehaveaskedusforanExportControlClassificationNumber(ECCN)forPuTTY.Wedon'tknowwhetherwehaveone,andasateamoffreesoftwaredevelopersbasedintheUKwedon'thavethetime,money,orefforttodealwithUSbureaucracytoinvestigateanyfurther.WebelievethatPuTTYfallsunder5D002ontheUSCommerceControlList,butthatshouldn'tbetakenasdefinitive.Ifyouneedtoknowmoreyoushouldseekprofessionallegaladvice.Thesameappliestoanyothercountry'slegalrequirementsandrestrictions.

Similarly,somepeoplehaveaskedusforFIPScertificationofthePuTTYtools.Unlesssomeoneelseispreparedtodothenecessaryworkandpayanycosts,wecan'tprovidethis.

A.9.15Asoneofourexistingsoftwarevendors,canyoujustfillinthisquestionnaireforus?Weperiodicallyreceiverequestslikethis,fromorganisationswhichhaveapparentlysentoutaformlettertoeveryonelistedintheirbigspreadsheetof‘softwarevendors’requiringthemalltoanswersomelonglistofquestionsaboutsupportedOSversions,paidsupportarrangements,compliancewithassortedlocalregulationswehaven'theardof,contactphonenumbers,andothersuchadministrivia.ManyofthequestionsareobviouslymeaninglesswhenappliedtoPuTTY(wedon'tprovideanypaidsupportinthefirstplace!),mostoftherestcouldhavebeenansweredwithonlyaveryquicklookatourwebsite,andsomeweareactivelyunwillingtoanswer(weareprivateindividuals,whywouldwewanttogiveoutourhomephonenumberstolargecorporations?).

Wedon'tmakeahabitofrespondinginfulltothesequestionnaires,becausewearenotasoftwarevendor.

Asoftwarevendorisacompanytowhichyouarepayinglotsofmoneyinreturnforsomesoftware.Theyknowwhoyouare,andtheyknowyou'repayingthemmoney;sotheyhaveanincentivetofillinyourformsandquestionnaires,toresearchanylocalregulationsyouciteiftheydon'talreadyknowaboutthem,andgenerallytoprovideeveryscrapofinformationyoumightpossiblyneedinthemostconvenientmannerforyou,becausetheywanttokeepbeingpaid.

Butweareateamoffreesoftwaredevelopers,andthatmeansyourrelationshipwithusisnothinglikethatatall.Ifyouoncedownloadedoursoftwarefromourwebsite,that'sgreatandwehopeyoufoundituseful,butitdoesn'tmeanwehavetheleastideawhoyouare,oranyincentivetodolotsofunpaidworktosupportour‘relationship’withyou.

It'snotthatweareunwillingtoprovideinformation.Weputasmuchofitaswecanonourwebsiteforyourconvenience,andifyouactuallyneedtoknowsomefactaboutPuTTYwhichyouhaven'tbeenabletofindonthewebsite(andwhichisnotobviouslyinapplicabletofreesoftwareinthefirstplace)thenpleasedoaskus,andwe'lltrytoanswerasbestwe

can.ButweputupthewebsiteandthisFAQpreciselysothatwedon'thavetokeepansweringthesamequestionsoverandoveragain,sowearen'tpreparedtofillincompletelygenericform-letterquestionnairesforpeoplewhohaven'tdonetheirbesttofindtheanswersherefirst.

Ifyouworkforanorganisationwhichyouthinkmightbeatriskofmakingthismistake,weurgeyoutoreorganiseyourlistofsoftwaresupplierssothatitclearlydistinguishespaidvendorswhoknowaboutyoufromfreesoftwaredeveloperswhodon'thaveanyideawhoyouare.Then,onlysendoutthesemassmailingstotheformer.

A.9.16Thesha1sums/sha256sums/etcfilesonyourdownloadpagedon'tmatchthebinaries.Peoplereportthiseverysooften,andusuallythereasonturnsouttobethatthey'vematchedupthewrongchecksumsfilewiththewrongbinaries.

ThePuTTYdownloadpagecontainsmorethanoneversionofthesoftware.There'salatestreleaseversion;therearethedevelopmentsnapshots;andwhenwe'reintherun-uptomakingarelease,therearealsopre-releasebuildsoftheupcomingnewversion.Eachonehasitsowncollectionofbinaries,anditsowncollectionofchecksumsfilestogowiththem.

Soifyou'vedownloadedthereleaseversionoftheactualprogram,youneedthereleaseversionofthechecksumstoo,otherwiseyouwillseeamismatch.Similarly,thedevelopmentsnapshotbinariesgowiththedevelopmentsnapshotchecksums,andsoon.(We'vecolour-codedthedownloadpageinanefforttoreducethisconfusionabit.)

Ifyouhavedouble-checkedthat,andyoustillthinkthere'sarealmismatch,thenpleasesendusareportcarefullyquotingeverythingrelevant:

theexactURLyougotyourbinaryfromthechecksumofthebinaryafteryoudownloadedtheexactURLyougotyourchecksumsfilefromthechecksumthatfilesaysthebinaryshouldhave.

A.10MiscellaneousquestionsA.10.1IsPuTTYaportofOpenSSH,orbasedonOpenSSHorOpenSSL?A.10.2WherecanIbuysillyputty?A.10.3Whatdoes‘PuTTY’mean?A.10.4HowdoIpronounce‘PuTTY’?

A.10.1IsPuTTYaportofOpenSSH,orbasedonOpenSSHorOpenSSL?No,itisn't.PuTTYisalmostcompletelycomposedofcodewrittenfromscratchforPuTTY.TheonlycodewesharewithOpenSSHisthedetectorforSSH-1CRCcompensationattacks,writtenbyCORESDIS.A;wesharenocodeatallwithOpenSSL.

A.10.2WherecanIbuysillyputty?You'relookingatthewrongwebsite;theonlyPuTTYweknowabouthereisthenameofacomputerprogram.

Ifyouwantthekindofputtyyoucanbuyasanexecutivetoy,thePuTTYteamcanpersonallyrecommendThinkingPutty,whichyoucanbuyfromCrazyAaron'sPuttyWorld,atwww.puttyworld.com.

A.10.3Whatdoes‘PuTTY’mean?It'sthenameofapopularSSHandTelnetclient.Anyothermeaningisintheeyeofthebeholder.It'sbeenrumouredthat‘PuTTY’istheantonymof‘getty’,orthatit'sthestuffthatmakesyourWindowsuseful,orthatit'sakindofplutoniumTeletype.Wecouldn'tpossiblycommentonsuchallegations.

A.10.4HowdoIpronounce‘PuTTY’?ExactlyliketheEnglishword‘putty’,whichwepronounce/ˈpʌti/.

AppendixB:FeedbackandbugreportingThisisaguidetoprovidingfeedbacktothePuTTYdevelopmentteam.ItisprovidedasbothawebpageonthePuTTYsite,andanappendixinthePuTTYmanual.

SectionB.1givessomegeneralguidelinesforsendinganykindofe-mailtothedevelopmentteam.Followingsectionsgivemorespecificguidelinesforparticulartypesofe-mail,suchasbugreportsandfeaturerequests.

B.1GeneralguidelinesB.1.1SendinglargeattachmentsB.1.2Otherplacestoaskforhelp

B.2ReportingbugsB.3ReportingsecurityvulnerabilitiesB.4RequestingextrafeaturesB.5RequestingfeaturesthathavealreadybeenrequestedB.6SupportrequestsB.7WebserveradministrationB.8AskingpermissionforthingsB.9MirroringthePuTTYwebsiteB.10PraiseandcomplimentsB.11E-mailaddress

B.1GeneralguidelinesThePuTTYdevelopmentteamgetsalotofmail.Ifyoucanpossiblysolveyourownproblembyreadingthemanual,readingtheFAQ,readingthewebsite,askingafellowuser,perhapspostingtoanewsgroup(seesectionB.1.2),orsomeothermeans,thenitwouldmakeourlivesmucheasier.

Wegetsomuche-mailthatweliterallydonothavetimetoansweritall.Weregretthis,butthere'snothingwecandoaboutit.SoifyoucanpossiblyavoidsendingmailtothePuTTYteam,werecommendyoudoso.Inparticular,supportrequests(sectionB.6)areprobablybettersenttonewsgroups,orpassedtoalocalexpertifpossible.

ThePuTTYcontactemailaddressisaprivatemailinglistcontainingfourorfivecoredevelopers.Don'tbeputoffbyitbeingamailinglist:ifyouneedtosendconfidentialdataaspartofabugreport,youcantrustthepeopleonthelisttorespectthatconfidence.Also,thearchivesaren'tpubliclyavailable,soyoushouldn'tbelettingyourselfinforanyspambysendingusmail.

Pleaseuseameaningfulsubjectlineonyourmessage.Wegetalotofmail,andit'shardtofindthemessagewe'relookingforiftheyallhavesubjectlineslike‘PuTTYbug’.

B.1.1SendinglargeattachmentsB.1.2Otherplacestoaskforhelp

B.1.1SendinglargeattachmentsSincethePuTTYcontactaddressisamailinglist,e-mailslargerthan40Kbwillbeheldforinspectionbythelistadministrator,andwillnotbeallowedthroughunlesstheyreallyappeartobeworththeirlargesize.

IfyouareconsideringsendinganykindoflargedatafiletothePuTTYteam,it'salmostalwaysabadidea,orattheveryleastitwouldbebettertoaskusfirstwhetherweactuallyneedthefile.Alternatively,youcouldputthefileonawebsiteandjustsendustheURL;thatway,wedon'thavetodownloaditunlesswedecideweactuallyneedit,andonlyoneofusneedstodownloaditinsteadofitbeingautomaticallycopiedtoallthedevelopers.

(Ifthefilecontainsconfidentialinformation,thenyoucouldencryptitwithourSecureContactKey;seesectionE.1fordetails.)

SomepeopleliketosendmailinMSWordformat.Pleasedon'tsendusbugreports,oranyothermail,asaWorddocument.Worddocumentsareroughlyfiftytimeslargerthanwritingthesamereportinplaintext.Inaddition,mostofthePuTTYteamreadtheire-mailonUnixmachines,socopyingthefiletoaWindowsboxtorunWordisveryinconvenient.Notonlythat,butseveralofusdon'tevenhaveacopyofWord!

Somepeopleliketosendusscreenshotswhendemonstratingaproblem.Pleasedon'tdothiswithoutcheckingwithusfirst-wealmostneveractuallyneedtheinformationinthescreenshot.Sendingascreenshotofanerrorboxisalmostcertainlyunnecessarywhenyoucouldjusttellusinplaintextwhattheerrorwas.(OnsomeversionsofWindows,pressingCtrl-Cwhentheerrorboxisdisplayedwillcopythetextofthemessagetotheclipboard.)Sendingafull-screenshotisoccasionallyuseful,butit'sprobablystillwisetocheckwhetherweneeditbeforesendingit.

Ifyoumustmailascreenshot,don'tsenditasa.BMPfile.BMPshavenocompressionandtheyaremuchlargerthanotherimageformatssuchasPNG,TIFFandGIF.Convertthefiletoaproperlycompressedimageformatbeforesendingit.

Pleasedon'tmailusexecutables,atall.Ourmailserverblocksallincominge-mailcontainingexecutables,asadefenceagainstthevastnumbersofe-mailviruseswereceiveeveryday.Ifyoumailusanexecutable,itwilljustbounce.

IfyouhavemadeatinymodificationtothePuTTYcode,pleasesendusapatchtothesourcecodeifpossible,ratherthansendingusahuge.ZIPfilecontainingthecompletesourcesplusyourmodification.Ifyou'veonlychanged10lines,we'dprefertoreceiveamailthat's30lineslongthanonecontainingmultiplemegabytesofdatawealreadyhave.

B.1.2OtherplacestoaskforhelpTherearetwoUsenetnewsgroupsthatareparticularlyrelevanttothePuTTYtools:

comp.security.ssh,forquestionsspecifictousingtheSSHprotocol;comp.terminals,forissuesrelatingtoterminalemulation(forinstance,keyboardproblems).

Pleaseusethenewsgroupmostappropriatetoyourquery,andrememberthatthesearegeneralnewsgroups,notspecificallyaboutPuTTY.

Ifyoudon'thavedirectaccesstoUsenet,youcanaccessthesenewsgroupsthroughGoogleGroups(groups.google.com).

B.2ReportingbugsIfyouthinkyouhavefoundabuginPuTTY,yourfirststepsshouldbe:

ChecktheWishlistpageonthePuTTYwebsite,andseeifwealreadyknowabouttheproblem.Ifwedo,itisalmostcertainlynotnecessarytomailusaboutit,unlessyouthinkyouhaveextrainformationthatmightbehelpfultousinfixingit.(Ofcourse,ifweactuallyneedspecificextrainformationaboutaparticularbug,theWishlistpagewillsayso.)ChecktheChangeLogonthePuTTYwebsite,andseeifwehavealreadyfixedthebuginthedevelopmentsnapshots.ChecktheFAQonthePuTTYwebsite(alsoprovidedasappendixAinthemanual),andseeifitanswersyourquestion.TheFAQliststhemostcommonthingswhichpeoplethinkarebugs,butwhicharen'tbugs.Downloadthelatestdevelopmentsnapshotandseeiftheproblemstillhappenswiththat.Thisreallyisworthdoing.Asageneralrulewearen'tveryinterestedinbugsthatappearinthereleaseversionbutnotinthedevelopmentversion,becausethatusuallymeanstheyarebugswehavealreadyfixed.Ontheotherhand,ifyoucanfindabuginthedevelopmentversionthatdoesn'tappearintherelease,that'slikelytobeanewbugwe'veintroducedsincethereleaseandwe'redefinitelyinterestedinit.

Ifnoneofthoseoptionssolvedyourproblem,andyoustillneedtoreportabugtous,itisusefulifyouincludesomegeneralinformation:

TelluswhatversionofPuTTYyouarerunning.Tofindthisout,usethe‘AboutPuTTY’optionfromtheSystemmenu.Pleasedonotjusttellus‘I'mrunningthelatestversion’;e-mailcanbedelayedanditmaynotbeobviouswhichversionwasthelatestatthetimeyousentthemessage.PuTTYisamulti-platformapplication;telluswhatversionofwhatOSyouarerunningPuTTYon.(Ifyou'rerunningonUnix,orWindowsforAlpha,tellus,orwe'llassumeyou'rerunningonWindowsforIntelasthisisoverwhelminglythecase.)Telluswhatprotocolyouareconnectingwith:SSH,Telnet,Rloginor

Rawmode.Telluswhatkindofserveryouareconnectingto;whatOS,andifpossiblewhatSSHserver(ifyou'reusingSSH).YoucangetsomeofthisinformationfromthePuTTYEventLog(seesection3.1.3.1inthemanual).SendusthecontentsofthePuTTYEventLog,unlessyouhaveaspecificreasonnotto(forexample,ifitcontainsconfidentialinformationthatyouthinkweshouldbeabletosolveyourproblemwithoutneedingtoknow).Trytogiveusasmuchinformationasyoucantohelpusseetheproblemforourselves.Ifpossible,giveusastep-by-stepsequenceofpreciseinstructionsforreproducingthefault.Don'tjusttellusthatPuTTY‘doesthewrongthing’;tellusexactlyandpreciselywhatitdid,andalsotellusexactlyandpreciselywhatyouthinkitshouldhavedoneinstead.SomepeopletellusPuTTYdoesthewrongthing,anditturnsoutthatitwasdoingtherightthingandtheirexpectationswerewrong.Helptoavoidthisproblembytellingusexactlywhatyouthinkitshouldhavedone,andexactlywhatitdiddo.Ifyouthinkyoucan,you'rewelcometotrytofixtheproblemyourself.Apatchtothecodewhichfixesabugisanexcellentadditiontoabugreport.However,apatchisneverasubstituteforagoodbugreport;ifyourpatchiswrongorinappropriate,andyouhaven'tsupplieduswithfullinformationabouttheactualbug,thenwewon'tbeabletofindabettersolution.https://www.chiark.greenend.org.uk/~sgtatham/bugs.htmlisanarticleonhowtoreportbugseffectivelyingeneral.Ifyourbugreportisparticularlyunclear,wemayaskyoutogoaway,readthisarticle,andthenreportthebugagain.

ItisreasonabletoreportbugsinPuTTY'sdocumentation,ifyouthinkthedocumentationisunclearorunhelpful.Butwedoneedtobegivenexactdetailsofwhatyouthinkthedocumentationhasfailedtotellyou,orhowyouthinkitcouldbemadeclearer.Ifyourproblemissimplythatyoudon'tunderstandthedocumentation,wesuggestpostingtoanewsgroup(seesectionB.1.2)andseeingifsomeonewillexplainwhatyouneedtoknow.Then,ifyouthinkthedocumentationcouldusefullyhavetoldyouthat,sendusabugreportandexplainhowyouthinkweshouldchangeit.

B.3ReportingsecurityvulnerabilitiesIfyou'vefoundasecurityvulnerabilityinPuTTY,youmightwellwanttonotifyususinganencryptedcommunicationschannel,toavoiddisclosinginformationaboutthevulnerabilitybeforeafixedreleaseisavailable.

Forthispurpose,weprovideaGPGkeysuitableforencryption:theSecureContactKey.SeesectionE.1fordetailsofthis.

(Ofcourse,vulnerabilitiesarealsobugs,sopleasedoincludeasmuchinformationaspossibleaboutthem,thesamewayyouwouldwithanyotherbugreport.)

B.4RequestingextrafeaturesIfyouwanttorequestanewfeatureinPuTTY,theveryfirstthingsyoushoulddoare:

ChecktheWishlistpageonthePuTTYwebsite,andseeifyourfeatureisalreadyonthelist.Ifitis,itprobablywon'tachieveverymuchtorepeattherequest.(ButseesectionB.5ifyouwanttopersuadeustogiveyourparticularfeaturehigherpriority.)ChecktheWishlistandChangeLogonthePuTTYwebsite,andseeifwehavealreadyaddedyourfeatureinthedevelopmentsnapshots.Ifitisn'tclear,downloadthelatestdevelopmentsnapshotandseeifthefeatureispresent.Ifitis,thenitwillalsobeinthenextreleaseandthereisnoneedtomailusatall.

Ifyoucan'tfindyourfeatureineitherthedevelopmentsnapshotsortheWishlist,thenyouprobablydoneedtosubmitafeaturerequest.SincethePuTTYauthorsareverybusy,ithelpsifyoutrytodosomeoftheworkforus:

Doasmuchofthedesignasyoucan.Thinkabout‘cornercases’;thinkabouthowyourfeatureinteractswithotherexistingfeatures.Thinkabouttheuserinterface;ifyoucan'tcomeupwithasimpleandintuitiveinterfacetoyourfeature,youshouldn'tbesurprisedifwecan'teither.Alwaysimaginewhetherit'spossiblefortheretobemorethanone,orlessthanone,ofsomethingyou'dassumedtherewouldbeoneof.(Forexample,ifyouweretowantPuTTYtoputaniconintheSystemtrayratherthantheTaskbar,youshouldthinkaboutwhathappensifthere'smorethanonePuTTYactive;howwouldtheusertellwhichwaswhich?)Ifyoucanprogram,itmaybeworthofferingtowritethefeatureyourselfandsendusapatch.However,itislikelytobehelpfulifyouconferwithusfirst;theremaybedesignissuesyouhaven'tthoughtof,orwemaybeabouttomakebigchangestothecodewhichyourpatchwouldclashwith,orsomething.Ifyoucheckwiththemaintainersfirst,thereisabetterchanceofyourcodeactuallybeingusable.Also,readthedesignprincipleslistedinappendixD:ifyoudonotconformtothem,wewillprobablynotbeabletoacceptyour

patch.

B.5RequestingfeaturesthathavealreadybeenrequestedIfafeatureisalreadylistedontheWishlist,thenitusuallymeanswewouldliketoaddittoPuTTYatsomepoint.However,thismaynotbeinthenearfuture.Ifthere'safeatureontheWishlistwhichyouwouldliketoseeinthenearfuture,thereareseveralthingsyoucandototrytoincreaseitsprioritylevel:

Mailusandvoteforit.(Besuretomentionthatyou'veseenitontheWishlist,orwemightthinkyouhaven'tevenreadtheWishlist).Thisprobablywon'thaveverymucheffect;ifahugenumberofpeoplevoteforsomethingthenitmaymakeadifference,butoneortwoextravotesforaparticularfeatureareunlikelytochangeourprioritylistimmediately.Offeringanewandcompellingjustificationmighthelp.Also,don'texpectareply.Offerusmoneyifwedotheworksoonerratherthanlater.Thissometimesworks,butnotalways.ThePuTTYteamallhavefull-timejobsandwe'redoingallofthisworkinourfreetime;wemaysometimesbewillingtogiveupsomemoreofourfreetimeinexchangeforsomemoney,butifyoutrytobribeusforabigfeatureit'sentirelypossiblethatwesimplywon'thavethetimetospare-whetheryoupayusornot.(Also,wedon'tacceptbribestoaddbadfeaturestotheWishlist,becauseourdesiretoprovidehigh-qualitysoftwaretotheuserscomesfirst.)Offertohelpuswritethecode.Thisisprobablytheonlywaytogetafeatureimplementedquickly,ifit'sabigonethatwedon'thavetimetodoourselves.

B.6SupportrequestsIfyou'retryingtomakePuTTYdosomethingforyouanditisn'tworking,butyou'renotsurewhetherit'sabugornot,thenpleaseconsiderlookingforhelpsomewhereelse.ThisisoneofthemostcommontypesofmailthePuTTYteamreceives,andwesimplydon'thavetimetoanswerallthequestions.Questionsofthistypeinclude:

IfyouwanttodosomethingwithPuTTYbuthavenoideawheretostart,andreadingthemanualhasn'thelped,trypostingtoanewsgroup(seesectionB.1.2)andseeifsomeonecanexplainittoyou.IfyouhavetriedtodosomethingwithPuTTYbutithasn'tworked,andyouaren'tsurewhetherit'sabuginPuTTYorabuginyourSSHserverorsimplythatyou'renotdoingitright,thentrypostingtoanewsgroup(seesectionB.1.2)andseeifsomeonecansolveyourproblem.OrtrydoingthesamethingwithadifferentSSHclientandseeifitworkswiththat.PleasedonotreportitasaPuTTYbugunlessyouarereallysureitisabuginPuTTY.IfsomeoneelseinstalledPuTTYforyou,oryou'reusingPuTTYonsomeoneelse'scomputer,tryaskingthemforhelpfirst.They'remorelikelytounderstandhowtheyinstalleditandwhattheyexpectedyoutouseitforthanweare.Ifyouhavesuccessfullymadeaconnectiontoyourserverandnowneedtoknowwhattotypeattheserver'scommandprompt,orotherdetailsofhowtousetheserver-endsoftware,talktoyourserver'ssystemadministrator.ThisisnotthePuTTYteam'sproblem.PuTTYisonlyacommunicationstool,likeatelephone;ifyoucan'tspeakthesamelanguageasthepersonattheotherendofthephone,itisn'tthetelephonecompany'sjobtoteachittoyou.

Ifyouabsolutelycannotgetasupportquestionansweredanyotherway,youcantrymailingittous,butwecan'tguaranteetohavetimetoanswerit.

B.7WebserveradministrationIfthePuTTYwebsiteisdown(ConnectionTimedOut),pleasedon'tbothermailingustotellusaboutit.Mostofusreadoure-mailonthesamemachinesthathostthewebsite,soifthosemachinesaredownthenwewillnoticebeforewereadoure-mail.Sothere'snopointtellingusourserversaredown.

Ofcourse,ifthewebsitehassomeothererror(ConnectionRefused,404NotFound,403Forbidden,orsomethingelse)thenwemightnothavenoticedanditmightstillbeworthtellingusaboutit.

Ifyouwanttoreportaproblemwithourwebsite,checkthatyou'relookingatourrealwebsiteandnotamirror.Therealwebsiteisathttps://www.chiark.greenend.org.uk/~sgtatham/putty/;ifthat'snotwhereyou'rereadingthis,thendon'treporttheproblemtousuntilyou'vecheckedthatit'sreallyaproblemwiththemainsite.Ifit'sonlyaproblemwiththemirror,youshouldtrytocontacttheadministratorofthatmirrorsitefirst,andonlycontactusifthatdoesn'tsolvetheproblem(incaseweneedtoremovethemirrorfromourlist).

B.8AskingpermissionforthingsPuTTYisdistributedundertheMITLicence(seeappendixCfordetails).Thismeansyoucandoalmostanythingyoulikewithoursoftware,oursourcecode,andourdocumentation.Theonlythingsyouaren'tallowedtodoaretoremoveourcopyrightnoticesorthelicencetextitself,ortoholduslegallyresponsibleifsomethinggoeswrong.

SoifyouwantpermissiontoincludePuTTYonamagazinecoverdisk,oraspartofacollectionofusefulsoftwareonaCDorawebsite,thenpermissionisalreadygranted.Youdon'thavetomailusandask.Justgoaheadanddoit.Wedon'tmind.

(IfyouwanttodistributePuTTYalongsideyourownapplicationforusewiththatapplication,orifyouwanttodistributePuTTYwithinyourownorganisation,thenwerecommend,butdonotinsist,thatyouofferyourownfirst-linetechnicalsupport,toanswerquestionsabouttheinteractionofPuTTYwithyourenvironment.Ifyourusersmailusdirectly,wewon'tbeabletotellthemanythingusefulaboutyourspecificsetup.)

IfyouwanttousepartsofthePuTTYsourcecodeinanotherprogram,thenitmightbeworthmailingustotalkabouttechnicaldetails,butifallyouwantistoaskpermissionthenyoudon'tneedtobother.Youalreadyhavepermission.

Ifyoujustwanttolinktoourwebsite,justgoahead.(It'snotclearthatwecouldstopyoudoingthis,evenifwewantedto!)

B.9MirroringthePuTTYwebsiteIfyouwanttosetupamirrorofthePuTTYwebsite,goaheadandsetoneup.Pleasedon'tbotheraskingusforpermissionbeforesettingupamirror.Youalreadyhavepermission.

Ifthemirrorisinacountrywherewedon'talreadyhaveplentyofmirrors,wemaybewillingtoaddittothelistonourmirrorspage.Readtheguidelinesonthatpage,makesureyourmirrorworks,andemailustheinformationlistedatthebottomofthepage.

Notethatwedonotpromisetolistyourmirror:wegetalotofmirrornotificationsandyoursmaynothappentofinditswaytothetopofthelist.

Alsonotethatwelinktoallourmirrorsitesusingtherel="nofollow"attribute.RunningaPuTTYmirrorisnotintendedtobeacheapwaytogainsearchrankings.

Ifyouhavetechnicalquestionsabouttheprocessofmirroring,thenyoumightwanttomailusbeforesettingupthemirror(seealsotheguidelinesontheMirrorspage);butifyoujustwanttoaskforpermission,youdon'tneedto.Youalreadyhavepermission.

B.10PraiseandcomplimentsOneofthemostrewardingthingsaboutmaintainingfreesoftwareisgettinge-mailsthatjustsay‘thanks’.Wearealwayshappytoreceivee-mailsofthistype.

Regrettablywedon'thavetimetoanswerthemallinperson.Ifyoumailusacomplimentanddon'treceiveareply,pleasedon'tthinkwe'veignoredyou.Wedidreceiveitandwewerehappyaboutit;wejustdidn'thavetimetotellyousopersonally.

Toeveryonewho'seversentuspraiseandcompliments,inthepastandthefuture:you'rewelcome!

B.11E-mailaddressTheactualaddresstomailis<putty@projects.tartarus.org>.

AppendixC:PuTTYLicencePuTTYiscopyright1997-2017SimonTatham.

PortionscopyrightRobertdeBath,JorisvanRantwijk,DelianDelchev,AndreasSchultz,JeroenMassar,WezFurlong,NicolasBarry,JustinBradford,BenHarris,MalcolmSmith,AhmadKhalifa,MarkusKuhn,ColinWatson,ChristopherStaite,andCORESDIS.A.

Permissionisherebygranted,freeofcharge,toanypersonobtainingacopyofthissoftwareandassociateddocumentationfiles(the‘Software’),todealintheSoftwarewithoutrestriction,includingwithoutlimitationtherightstouse,copy,modify,merge,publish,distribute,sublicense,and/orsellcopiesoftheSoftware,andtopermitpersonstowhomtheSoftwareisfurnishedtodoso,subjecttothefollowingconditions:

TheabovecopyrightnoticeandthispermissionnoticeshallbeincludedinallcopiesorsubstantialportionsoftheSoftware.

THESOFTWAREISPROVIDED‘ASIS’,WITHOUTWARRANTYOFANYKIND,EXPRESSORIMPLIED,INCLUDINGBUTNOTLIMITEDTOTHEWARRANTIESOFMERCHANTABILITY,FITNESSFORAPARTICULARPURPOSEANDNONINFRINGEMENT.INNOEVENTSHALLTHECOPYRIGHTHOLDERSBELIABLEFORANYCLAIM,DAMAGESOROTHERLIABILITY,WHETHERINANACTIONOFCONTRACT,TORTOROTHERWISE,ARISINGFROM,OUTOFORINCONNECTIONWITHTHESOFTWAREORTHEUSEOROTHERDEALINGSINTHESOFTWARE.

AppendixD:PuTTYhackingguideThisappendixlistsaselectionofthedesignprinciplesapplyingtothePuTTYsourcecode.Ifyouareplanningtosendcodecontributions,youshouldreadthisfirst.

D.1Cross-OSportabilityD.2MultiplebackendstreatedequallyD.3MultiplesessionsperprocessonsomeplatformsD.4C,notC++D.5Security-consciouscodingD.6IndependenceofspecificcompilerD.7SmallcodesizeD.8Single-threadedcodeD.9KeystrokessenttotheserverwhereverpossibleD.10640×480friendlinessinconfigurationpanelsD.11AutomaticallygeneratedMakefilesD.12Coroutinesinssh.cD.13SinglecompilationofeachsourcefileD.14Doaswesay,notaswedo

D.1Cross-OSportabilityDespiteWindowsbeingitsmainareaoffame,PuTTYisnolongeraWindows-onlyapplicationsuite.IthasaworkingUnixport;aMacportisinprogress;moreportsmayormaynothappenatalaterdate.

Therefore,embeddingWindows-specificcodeincoremodulessuchasssh.cisnotacceptable.WewenttogreatlengthstoremovealltheWindows-specificstufffromourcoremodules,andtoshiftitoutintoWindows-specificmodules.AddinglargeamountsofWindows-specificstuffinpartsofthecodethatshouldbeportableisalmostguaranteedtomakeusrejectacontribution.

ThePuTTYsourcebaseisdividedintoplatform-specificmodulesandplatform-genericmodules.TheUnix-specificmodulesareallintheunixsubdirectory;theMac-specificmodulesareinthemacsubdirectory;theWindows-specificmodulesareinthewindowssubdirectory.

Allthemodulesinthemainsourcedirectory-notablyallofthecodeforthevariousbackends-areplatform-generic.Wewanttokeepthemthatway.

ThisalsomeansyoushouldsticktowhatyouareguaranteedbyANSI/ISOC(thatis,theoriginalC89/C90standard,notC99).Trynottomakeassumptionsabouttheprecisesizeofbasictypessuchasintandlongint;don'tusepointercaststodoendianness-dependentoperations,andsoon.

(ThereareoneortwoaspectsofANSICportabilitywhichwedon'tcareabout.Inparticular,weexpectPuTTYtobecompiledon32-bitarchitecturesorbigger;soit'ssafetoassumethatintisatleast32bitswide,notjustthe16youareguaranteedbyANSIC.Similarly,weassumethattheexecutioncharacterencodingisasupersetoftheprintablecharactersofASCII,thoughwedon'tassumethenumericvaluesofcontrolcharacters,particularly'\n'and'\r'.Also,theXforwardingcodeassumesthattime_thastheUnixformatandsemantics,i.e.anintegergivingthenumberofsecondssince1970.)

D.2MultiplebackendstreatedequallyPuTTYisnotanSSHclientwithsomeotherstufftackedontheside.PuTTYisageneric,multiple-backend,remoteVT-terminalclientwhichhappenstosupportonebackendwhichislarger,morepopularandmoreusefulthantherest.Anyextrafeaturewhichcanpossiblybegeneralacrossallbackendsshouldbeso:localisingfeaturesunnecessarilyintotheSSHbackendisadesignerror.(Forexample,wehadseveralcodesubmissionsforproxysupportwhichworkedbyhackingssh.c.Clearlythisiscompletelywrong:thenetwork.habstractionistheplacetoputit,sothatitwillapplytoallbackendsequally,andindeedweeventuallyputitthereafteranothercontributorsentabetterpatch.)

TherestofPuTTYshouldtrytoavoidknowinganythingaboutspecificbackendsifatallpossible.Tosupportafeaturewhichisonlyavailableinonenetworkprotocol,forexample,thebackendinterfaceshouldbeextendedinageneralmannersuchthatanybackendwhichisabletoprovidethatfeaturecandoso.Ifitsohappensthatonlyonebackendactuallydoes,that'sjustthewayitis,butitshouldn'tberelieduponbyanycode.

D.3MultiplesessionsperprocessonsomeplatformsSomeportsofPuTTY-notablythein-progressMacport-areconstrainedbytheoperatingsystemtorunasasingleprocesspotentiallymanagingmultiplesessions.

Therefore,theplatform-independentpartsofPuTTYneveruseglobalvariablestostoreper-sessiondata.Theglobalvariablesthatdoexistaretoleratedbecausetheyarenotspecifictoaparticularloginsession:flagsdefinespropertiesthatareexpectedtoapplyequallytoallthesessionsrunbyasinglePuTTYprocess,therandomnumberstateinsshrand.candthetimerlistintiming.cserveallsessionsequally,andsoon.Butmostdataisspecifictoaparticularnetworksession,andisthereforestoredindynamicallyallocateddatastructures,andpointerstothesestructuresarepassedaroundbetweenfunctions.

Platform-specificcodecanreversethisdecisionifitlikes.TheWindowscode,forhistoricalreasons,storesmostofitsdataasglobalvariables.That'sOK,becauseonWindowsweknowthereisonlyonesessionperPuTTYprocess,soit'ssafetodothat.Butchangestotheplatform-independentcodeshouldavoidintroducingglobalvariables,unlesstheyaregenuinelycross-session.

D.4C,notC++PuTTYiswrittenentirelyinC,notinC++.

WehavemadesomeefforttomakeiteasytocompileourcodeusingaC++compiler:notably,oursnew,snewnandsresizemacrosexplicitlycastthereturnvaluesofmallocandrealloctothetargettype.(ThishastypecheckingadvantageseveninC:itmeansyouneveraccidentallyallocatethewrongsizepieceofmemoryforthepointertypeyou'reassigningitto.C++friendlinessisreallyasidebenefit.)

WewantPuTTYtocontinuebeingpureC,atleastintheplatform-independentpartsandthecurrentlyexistingports.PatcheswhichswitchtheMakefilestocompileitasC++andstartusingclasseswillnotbeaccepted.Also,inparticular,wedisapproveof//comments,atleastforthemoment.(PerhapsonceC99becomesgenuinelywidespreadwemightbemorelenient.)

Theoneexception:aporttoanewplatformmayuselanguagesotherthanCiftheyarenecessarytocodeonthatplatform.IfyourfavouritePDAhasaGUIwithaC++API,thenthere'snowayyoucandoaportofPuTTYwithoutusingC++,sogoaheadanduseit.ButkeeptheC++restrictedtothatplatform'ssubdirectory;ifyourchangesforcetheUnixorWindowsportstobecompiledasC++,theywillbeunacceptabletous.

D.5Security-consciouscodingPuTTYisanetworkapplicationandasecurityapplication.Assumeyourcodewillendupbeingfeddeliberatelymaliciousdatabyattackers,andtrytocodeinawaythatmakesitunlikelytobeasecurityrisk.

Inparticular,trynottousefixed-sizebuffersforvariable-sizedatasuchasstringsreceivedfromthenetwork(oreventheuser).Weprovidefunctionssuchasdupcatanddupprintf,whichdynamicallyallocatebuffersoftherightsizeforthestringtheyconstruct.Usethesewhereverpossible.

D.6IndependenceofspecificcompilerWindowsPuTTYcancurrentlybecompiledwithanyoffourWindowscompilers:MSVisualC,Borland'sfreelydownloadableCcompiler,theCygwin/mingw32GNUtools,andlcc-win32.

ThisisareallyusefulpropertyofPuTTY,becauseitmeanspeoplewhowanttocontributetothecodingdon'tdependonhavingaspecificcompiler;sotheydon'thavetoforkoutmoneyforMSVCiftheydon'talreadyhaveit,butontheotherhandiftheydohaveittheyalsodon'thavetospendeffortinstallinggccalongsideit.Theycanusewhichevercompilertheyhappentohaveavailable,orinstallwhicheverischeapestandeasiestiftheydon'thaveone.

Therefore,wedon'twantPuTTYtostartdependingonwhichcompileryou'reusing.UsingGNUextensionstotheClanguage,forexample,wouldruinthisusefulproperty(notthatanyone'severtriedit!);andmorerealistically,dependingonanMS-specificlibraryfunctionsuppliedbytheMSVCClibrary(_snprintf,forexample)isamistake,becausethatfunctionwon'tbeavailableundertheothercompilers.AnyfunctionsuppliedinanofficialWindowsDLLaspartoftheWindowsAPIisfine,andanythingdefinedintheClibrarystandardisalsofine,becausethoseshouldbeavailableirrespectiveofcompilationenvironment.Butthingsinbetween,availableasnon-standardlibraryandlanguageextensionsinonlyonecompiler,aredisallowed.

(_snprintfinparticularshouldbeunnecessary,sinceweprovidedupprintf;seesectionD.5.)

Compilerindependenceshouldapplyonallplatforms,ofcourse,notjustonWindows.

D.7SmallcodesizePuTTYistiny,comparedtomanyotherWindowsapplications.Andit'seasytoinstall:itdependsonnoDLLs,nootherapplications,noservicepacksorsystemupgrades.It'sjustoneexecutable.Youinstallthatexecutablewhereveryouwantto,andrunit.

Wewanttokeepboththeseproperties-thesmallsize,andtheeaseofinstallation-ifatallpossible.SocodecontributionsthatdependcriticallyonexternalDLLs,orthataddahugeamounttothecodesizeforafeaturewhichisonlyusefultoasmallminorityofusers,arelikelytobethrownoutimmediately.

WedovaguelyintendtointroduceaDLLplugininterfaceforPuTTY,wherebyseriouslylargeextrafeaturescanbeimplementedinpluginmodules.Theimportantthing,though,isthatthoseDLLswillbeoptional;ifPuTTYcan'tfindthemonstartup,itshouldrunperfectlyhappilyandjustwon'tprovidethoseparticularfeatures.AfullinstallationofPuTTYmightonedaycontaintenortwentylittleDLLplugins,whichwouldcutdownalittleontheeaseofinstallation-butifyoureallyneededeaseofinstallationyoucouldstilljustinstalltheonePuTTYbinary,orjusttheDLLsyoureallyneeded,anditwouldstillworkfine.

DependingonexternalDLLsissomethingwe'dliketoavoidifatallpossible(thoughforsomepurposes,suchascomplexSSHauthenticationmechanisms,itmaybeunavoidable).Ifitcan'tbeavoided,theimportantthingistofollowthesameprincipleofgracefuldegradation:ifaDLLcan'tbefound,thenPuTTYshouldrunhappilyandjustnotsupplythefeaturethatdependedonit.

D.8Single-threadedcodePuTTYanditssupportingtools,oratleastthevastmajorityofthem,runinonlyoneOSthread.

Thismeansthatifyou'redevisingsomepieceofinternalmechanism,there'snoneedtouselockstomakesureitdoesn'tgetcalledbytwothreadsatonce.Theonlywaycodecanbecalledre-entrantlyisbyrecursion.

Thatsaid,mostofWindowsPuTTY'snetworkhandlingistriggeredoffWindowsmessagesrequestedbyWSAAsyncSelect(),soifyoucallMessageBox()deepwithinsomenetworkeventhandlingcodeyoushouldbeawarethatyoumightbere-enteredifanetworkeventcomesinandispassedontoourwindowprocedurebytheMessageBox()messageloop.

Also,thefrontends(inparticularWindowsPlink)canusemultiplethreadsiftheylike.However,WindowsPlinkkeepsverytightcontrolofitsauxiliarythreads,andusesthemprettymuchexclusivelyasaformofselect().Prettymuchallthecodeoutsidewindows/winplink.cisonlyevercalledfromtheoneprimarythread;theothersjustlooproundblockingonfilehandlesandsendmessagestothemainthreadwhensomerealworkneedsdoing.Thisisnotconsideredaportabilityhazardbecausethatbitofwindows/winplink.cwillneedrewritingonotherplatformsinanycase.

Oneimportantconsequenceofthis:PuTTYhasonlyonethreadinwhichtodoeverything.That‘everything’mayincludemanagingmorethanoneloginsession(sectionD.3),managingmultipledatachannelswithinanSSHsession,respondingtoGUIeventsevenwhennothingishappeningonthenetwork,andrespondingtonetworkrequestsfromtheserver(suchasrepeatkeyexchange)evenwhentheprogramisdealingwithcomplexuserinteractionsuchasthere-configurationdialogbox.ThismeansthatalmostnoneofthePuTTYcodecansafelyblock.

D.9KeystrokessenttotheserverwhereverpossibleInalmostallcases,PuTTYsendskeystrokestotheserver.EvenweirdkeystrokesthatyouthinkshouldbehotkeyscontrollingPuTTY.EvenAlt-F4orAlt-Space,forexample.Ifakeystrokehasawell-definedescapesequencethatitcouldusefullybesendingtotheserver,thenitshoulddoso,orattheveryleastitshouldbeconfigurablyabletodoso.

TounconditionallyturnakeycombinationintoahotkeytocontrolPuTTYisalmostalwaysadesignerror.Ifahotkeyisreallytrulyrequired,thentrytofindakeycombinationforitwhichisn'talreadyusedinexistingPuTTYs(eitheritsendsnothingtotheserver,oritsendsthesamethingassomeothercombination).Eventhen,bepreparedforthepossibilitythatonedaythatkeycombinationmightendupbeingneededtosendsomethingtotheserver-somakesurethatthere'sanalternativewaytoinvokewhateverPuTTYfeatureitcontrols.

D.10640×480friendlinessinconfigurationpanelsThere'sareasonwehavelotsoftinyconfigurationpanelsinsteadofafewhugeones,andthatreasonisthatnoteveryonehasa1600×1200desktop.640×480isstillaviableresolutionforrunningWindows(andindeedit'sstillthedefaultifyoustartupinsafemode),soit'sstillaresolutionwecareabout.

Accordingly,thePuTTYconfigurationbox,andthePuTTYgencontrolwindow,aredeliberatelykeptjustsmallenoughtofitcomfortablyona640×480display.Ifyou'readdingcontrolstoeitheroftheseboxesandyoufindyourselfwantingtoincreasethesizeofthewholebox,don't.Splititintomorepanelsinstead.

D.11AutomaticallygeneratedMakefilesPuTTYisintendedtocompileonmultipleplatforms,andwithmultiplecompilers.ItwouldbehorrifyingtotrytomaintainasingleMakefilewhichhandledallpossiblesituations,andjustaspainfultotrytodirectlymaintainasetofmatchingMakefilesforeachdifferentcompilationenvironment.

Therefore,wehavemovedtheproblemupbyonelevel.InthePuTTYsourcearchiveisafilecalledRecipe,whichlistswhichsourcefilescombinetoproducewhichbinaries;andthereisalsoascriptcalledmkfiles.pl,whichreadsRecipeandwritesouttherealMakefiles.(Thescriptalsoreadsallthesourcefilesandanalysestheirdependenciesonheaderfiles,sowegetanextrabenefitfromdoingitthisway,whichisthatwecansupplycorrectdependencyinformationeveninenvironmentswhereit'sdifficulttosetupanautomatedmakedependphase.)

YoushouldnevereditanyofthePuTTYMakefilesdirectly.Theyarenotstoredinoursourcerepositoryatall.Theyareautomaticallygeneratedbymkfiles.plfromthefileRecipe.

Ifyouneedtoaddanewobjectfiletoaparticularbinary,therightthingtodoistoeditRecipeandre-runmkfiles.pl.Thiswillcausethenewobjectfiletobeaddedineverytoolthatrequiresit,oneveryplatformwhereitmatters,ineveryMakefiletowhichitisrelevant,andtogetallthedependencydataright.

IfyousendusapatchthatmodifiesoneoftheMakefiles,youjustwasteourtime,becausewewillhavetoconvertitintoachangetoRecipe.IfyousendusapatchthatmodifiesalloftheMakefiles,youwillhavewastedalotofyourtimeaswell!

(ThereisacommentatthetopofeveryMakefileinthePuTTYsourcearchivesayingthis,butmanypeopledon'tseemtoreadit,soit'sworthrepeatinghere.)

D.12Coroutinesinssh.cLargepartsofthecodeinssh.carestructuredusingasetofmacrosthatimplement(somethingcloseto)DonaldKnuth's‘coroutines’conceptinC.

Essentially,thepurposeofthesemacrosaretoarrangethatafunctioncancallcrReturn()toreturntoitscaller,andthenexttimeitiscalledcontrolwillresumefromjustafterthatcrReturnstatement.

Thismeansthatanylocal(automatic)variablesdeclaredinsuchafunctionwillbecorruptedeverytimeyoucallcrReturn.Ifyouneedavariabletopersistforlongerthanthat,youmustmakeitafieldinoneofthepersistentstatestructures:eitherthelocalstatestructuressorstineachfunction,orthebackend-widestructuressh.

Seehttps://www.chiark.greenend.org.uk/~sgtatham/coroutines.htmlforamorein-depthdiscussionofwhatthesemacrosareforandhowtheywork.

D.13SinglecompilationofeachsourcefileThePuTTYbuildsystemforanygivenplatformworksonthefollowingverysimplemodel:

Eachsourcefileiscompiledpreciselyonce,toproduceasingleobjectfile.Eachbinaryiscreatedbylinkingtogethersomecombinationofthoseobjectfiles.

Therefore,ifyouneedtointroducefunctionalitytoaparticularmodulewhichisonlyavailableinsomeofthetoolbinaries(forexample,acryptographicproxyauthenticationmechanismwhichneedstobeleftoutofPuTTYteltomaintainitsusabilityincrypto-hostilejurisdictions),thewrongwaytodoitisbyadding#ifdefsin(say)proxy.c.Thiswouldrequireseparatecompilationofproxy.cforPuTTYandPuTTYtel,whichmeansthattheentireMakefile-generationarchitecture(seesectionD.11)wouldhavetobesignificantlyredesigned.Unlessyouarepreparedtodothatredesignyourself,andguaranteethatitwillstillporttoanyfutureplatformswemightdecidetorunon,youshouldnotattemptthis!

Therightwaytointroduceafeaturelikethisistoputthenewcodeinaseparatesourcefile,and(ifnecessary)introduceasecondnewsourcefiledefiningthesamesetoffunctions,butdefiningthemasstubswhichdon'tprovidethefeature.Thenthemodulewhosebehaviourneedstovary(proxy.cinthisexample)cancallthefunctionsdefinedinthesetwomodules,anditwilleitherprovidethenewfeatureornotprovideitaccordingtowhichofyournewmodulesitislinkedwith.

Ofcourse,objectfilesareneversharedbetweenplatforms;soitisallowabletouse#ifdeftoselectbetweenplatforms.Thishappensinputtyps.h(choosingwhichoftheplatform-specificincludefilestouse),andalsoinmisc.c(theWindows-specific‘Minefield’memorydiagnosticsystem).Itshouldbeusedsparingly,though,ifatall.

D.14Doaswesay,notaswedoThecurrentPuTTYcodeprobablydoesnotconformstrictlytoalloftheprincipleslistedabove.TheremaybetheoccasionalSSH-specificpieceofcodeinwhatshouldbeabackend-independentmodule,ortheoccasionaldependenceonanon-standardXlibraryfunctionunderUnix.

Thisshouldnotbetakenasalicencetogoaheadandviolatetherules.Whereweviolatethemourselves,we'renothappyaboutit,andwewouldwelcomepatchesthatfixanyexistingproblems.Pleasetrytohelpusmakeourcodebetter,notworse!

AppendixE:PuTTYdownloadkeysandsignaturesWecreateGPGsignaturesforallthePuTTYfilesdistributedfromourwebsite,sothatuserscanbeconfidentthatthefileshavenotbeentamperedwith.Hereweidentifyourpublickeys,andexplainoursignaturepolicysoyoucanhaveanaccurateideaofwhateachsignatureguarantees.ThisdescriptionisprovidedasbothawebpageonthePuTTYsite,andanappendixinthePuTTYmanual.

Asofrelease0.58,allofthePuTTYexecutablescontainfingerprintmaterial(usuallyaccessedviathe-pgpfpcommand-lineoption),suchthatifyouhaveanexecutableyoutrust,youcanuseittoestablishatrustpath,forinstancetoanewerversiondownloadedfromtheInternet.

(Notethatnoneofthekeys,signatures,etcmentionedherehaveanythingtodowithkeysusedwithSSH-theyarepurelyforverifyingtheoriginoffilesdistributedbythePuTTYteam.)

E.1PublickeysE.2Securitydetails

E.2.1TheDevelopmentSnapshotskeyE.2.2TheReleaseskeyE.2.3TheSecureContactKeyE.2.4TheMasterKeys

E.3Keyrollover

E.1PublickeysWemaintainmultiplekeys,storedwithdifferentlevelsofsecurityduetobeingusedindifferentways.SeesectionE.2belowfordetails.

Thekeysweprovideare:

SnapshotKeyUsedtosignroutinedevelopmentbuildsofPuTTY:nightlysnapshots,pre-releases,andsometimesalsocustomdiagnosticbuildswesendtoparticularusers.

ReleaseKeyUsedtosignmanuallyreleasedversionsofPuTTY.

SecureContactKeyAnencryption-capablekeysuitableforpeopletosendconfidentialmessagestothePuTTYteam,e.g.reportsofvulnerabilities.

MasterKeyUsedtotiealltheabovekeysintotheGPGweboftrust.TheMasterKeysignsalltheotherkeys,andotherGPGusershavesigneditinturn.

ThecurrentissueofthosekeysareavailablefordownloadfromthePuTTYwebsite,andarealsoavailableonPGPkeyserversusingthekeyIDslistedbelow.

MasterKeyRSA,4096-bit.KeyID:4096R/04676F7C(longversion:4096R/AB585DC604676F7C).Fingerprint:440DE3B5B7A1CA85B3CC1718AB585DC604676F7C

ReleaseKeyRSA,2048-bit.KeyID:2048R/B43434E4(longversion:2048R/9DFE2648B43434E4).Fingerprint:0054DDAA8ADA15D2768A6DE79DFE2648B43434E4

SecureContactKeyRSA,2048-bit.MainkeyID:2048R/8A0AF00B(longversion:2048R/C4FCAAD08A0AF00B).EncryptionsubkeyID:2048R/50C2CF5C(longversion:2048R/9EB39CC150C2CF5C).Fingerprint:8A26250E763FE35975F3118FC4FCAAD08A0AF00B

SnapshotKey

RSA,2048-bit.KeyID:2048R/D15F7E8A(longversion:2048R/EEF20295D15F7E8A).Fingerprint:0A3B0048FE499B67A234FEB6EEF20295D15F7E8A

E.2SecuritydetailsThevariouskeyshavevariousdifferentsecuritylevels.Thissectionexplainswhatthosesecuritylevelsare,andhowfaryoucanexpecttotrusteachkey.

E.2.1TheDevelopmentSnapshotskeyE.2.2TheReleaseskeyE.2.3TheSecureContactKeyE.2.4TheMasterKeys

E.2.1TheDevelopmentSnapshotskeyTheDevelopmentSnapshotsprivatekeyisstoredwithoutapassphrase.Thisisnecessary,becausethesnapshotsaregeneratedeverynightwithouthumanintervention,sonobodywouldbeabletotypeapassphrase.

Thesnapshotsarebuiltandsignedonateammember'shomecomputers,beforebeinguploadedtothewebserverfromwhichyoudownloadthem.

Therefore,asignaturefromtheDevelopmentSnapshotskeyDOESprotectyouagainst:

PeopletamperingwiththePuTTYbinariesbetweenthePuTTYwebsiteandyou.Themaintainersofourwebserverattemptingtoabusetheirrootprivilegetotamperwiththebinaries.

ButitDOESNOTprotectyouagainst:

Peopletamperingwiththebinariesbeforetheyareuploadedtoourdownloadservers.Peopletamperingwiththebuildmachinessothatthenextsetofbinariestheybuildwillbemaliciousinsomeway.Peoplestealingtheunencryptedprivatekeyfromthebuildmachineitliveson.

Ofcourse,wetakeallreasonableprecautionstoguardthebuildmachines.Butwhenyouseeasignature,youshouldalwaysbecertainofpreciselywhatitguaranteesandpreciselywhatitdoesnot.

E.2.2TheReleaseskeyTheReleaseskeyismoresecure:becauseitisonlyusedatreleasetime,tosigneachreleasebyhand,wecanstoreitencrypted.

TheReleasesprivatekeyiskeptencryptedonthedevelopers'ownlocalmachines.Soanattackerwantingtostealitwouldhavetoalsostealthepassphrase.

E.2.3TheSecureContactKeyTheSecureContactKeyisstoredwithasimilarlevelofsecuritytotheReleaseKey:itisstoredwithapassphrase,andnoautomatedscripthasaccesstoit.

E.2.4TheMasterKeysTheMasterKeysignsalmostnothing.Itspurposeistobindtheotherkeystogetherandcertifythattheyareallownedbythesamepeopleandpartofthesameintegratedsetup.TheonlysignaturesproducedbytheMasterKey,ever,shouldbethesignaturesontheotherkeys.

TheMasterKeyisespeciallylong,anditsprivatekeyandpassphrasearestoredwithspecialcare.

Wehavecollectedsomethird-partysignaturesontheMasterKey,inordertoincreasethechancesthatyoucanfindasuitabletrustpathtothem.

Wehaveuploadedourvariouskeystopublickeyservers,sothatevenifyoudon'tknowanyofthepeoplewhohavesignedourkeys,youcanstillbereasonablyconfidentthatanattackerwouldfindithardtosubstitutefakekeysonallthepublickeyserversatonce.

E.3KeyrolloverOurcurrentkeysweregeneratedinSeptember2015,exceptfortheSecureContactKeywhichwasgeneratedinFebruary2016(wedidn'tthinkofituntillater).

Priortothat,wehadamucholdersetofkeysgeneratedin2000.Foreachofthekeytypesabove(otherthantheSecureContactKey),weprovidedbothanRSAkeyandaDSAkey(becauseatthetimewegeneratedthem,RSAwasnotinpracticeavailabletoeveryone,duetoexportrestrictions).

ThenewMasterKeyissignedwithbothoftheoldones,toshowthatitreallyisownedbythesamepeopleandnotsubstitutedbyanattacker.Also,wehaveretrospectivelysignedtheoldReleaseKeyswiththenewMasterKey,incaseyou'retryingtoverifythesignaturesonareleasepriortotherolloverandcanfindachainoftrusttothosekeysfromanyofthepeoplewhohavesignedournewMasterKey.

Futurereleaseswillbesignedwiththeup-to-datekeysshownabove.ReleasespriortotherolloveraresignedwiththeoldReleaseKeys.

Forcompleteness,thoseoldkeysaregivenhere:

MasterKey(originalRSA)RSA,1024-bit.KeyID:1024R/1E34AC41(longversion:1024R/9D5877BF1E34AC41).Fingerprint:8F1597DA2530AB0D88D1925411CF0C4C

MasterKey(originalDSA)DSA,1024-bit.KeyID:1024D/6A93B34E(longversion:1024D/4F5E6DF56A93B34E).Fingerprint:313C3E764B74C2C5F2AE83A84F5E6DF56A93B34E

ReleaseKey(originalRSA)RSA,1024-bit.KeyID:1024R/B41CAE29(longversion:1024R/EF39CCC0B41CAE29).Fingerprint:AE65D3F785D318E03B0C9B02FF3A81FE

ReleaseKey(originalDSA)DSA,1024-bit.KeyID:1024D/08B0A90B(longversion:1024D/FECD6F3F08B0A90B).Fingerprint:

00B1100938E698006518F0ABFECD6F3F08B0A90B

SnapshotKey(originalRSA)RSA,1024-bit.KeyID:1024R/32B903A9(longversion:1024R/FAAED21532B903A9).Fingerprint:868B1F799CF47FBD8B1BD78EC64E4C03

SnapshotKey(originalDSA)DSA,1024-bit.KeyID:1024D/7D3E4A00(longversion:1024D/165E56F77D3E4A00).Fingerprint:63DD8EF832F5D7779FF02947165E56F77D3E4A00

AppendixF:SSH-2namesspecifiedforPuTTYTherearevariouspartsoftheSSH-2protocolwherethingsarespecifiedusingatextualname.Namesendingin@putty.projects.tartarus.orgarereservedforallocationbythePuTTYteam.Allocatednamesaredocumentedhere.

F.1ConnectionprotocolchannelrequestnamesF.2KeyexchangemethodnamesF.3Encryptionalgorithmnames

F.1ConnectionprotocolchannelrequestnamesThesenamescanbesentinaSSH_MSG_CHANNEL_REQUESTmessage.

simple@putty.projects.tartarus.org

Thisissentbyaclienttoannouncethatitwillnothavemorethanonechannelopenatatimeinthecurrentconnection(thatonebeingtheonetherequestissenton).Theintentionisthattheserver,knowingthis,cansetthewindowonthatonechanneltosomethingverylarge,andleaveflowcontroltoTCP.Thereisnomessage-specificdata.

winadj@putty.projects.tartarus.org

PuTTYsendsthisrequestalongwithsomeSSH_MSG_CHANNEL_WINDOW_ADJUSTmessagesaspartofitswindow-sizetuning.Itcanbesentonanytypeofchannel.Thereisnomessage-specificdata.ServersMUSTtreatitasanunrecognisedrequestandrespondwithSSH_MSG_CHANNEL_FAILURE.

(SomeSSHserversgetconfusedbythismessage,sothereisabug-compatibilitymodefordisablingit.Seesection4.27.5.)

F.2Keyexchangemethodnamesrsa-sha1-draft-00@putty.projects.tartarus.org

rsa-sha256-draft-00@putty.projects.tartarus.org

rsa1024-sha1-draft-01@putty.projects.tartarus.org

rsa1024-sha256-draft-01@putty.projects.tartarus.org

rsa2048-sha256-draft-01@putty.projects.tartarus.org

rsa1024-sha1-draft-02@putty.projects.tartarus.org

rsa2048-sha512-draft-02@putty.projects.tartarus.org

rsa1024-sha1-draft-03@putty.projects.tartarus.org

rsa2048-sha256-draft-03@putty.projects.tartarus.org

rsa1024-sha1-draft-04@putty.projects.tartarus.org

rsa2048-sha256-draft-04@putty.projects.tartarus.org

TheseappearedinvariousdraftsofwhateventuallybecameRFC4432.Theyhavebeensupersededbyrsa1024-sha1andrsa2048-sha256.

F.3Encryptionalgorithmnamesarcfour128-draft-00@putty.projects.tartarus.org

arcfour256-draft-00@putty.projects.tartarus.org

ThesewereusedindraftsofwhateventuallybecameRFC4345.Theyhavebeensupersededbyarcfour128andarcfour256.