Helix Versioning Engine Administrator Guide:Multi-Site

Deployment2018.1

March 2018

Copyright1999-2018PerforceSoftware.

Allrightsreserved.

PerforceSoftwareanddocumentationisavailablefromwww.perforce.com.YoucandownloadandusePerforceprograms,butyoucannotsellorredistributethem.Youcandownload,print,copy,edit,andredistributethedocumentation,butyoucannotsellit,orsellanydocumentationderivedfromit.Youcannotmodifyorattempttoreverseengineertheprograms.

ThisproductissubjecttoU.S.exportcontrollawsandregulationsincluding,butnotlimitedto,theU.S.ExportAdministrationRegulations,theInternationalTrafficinArmsRegulationrequirements,andallapplicableend-use,end-useranddestinationrestrictions.Licenseeshallnotpermit,directlyorindirectly,useofanyPerforcetechnologyinorbyanyU.S.embargoedcountryorotherwiseinviolationofanyU.S.exportcontrollawsandregulations.

PerforceprogramsanddocumentsareavailablefromourWebsiteasis.Nowarrantyorsupportisprovided.Warrantiesandsupport,alongwithhighercapacityservers,aresoldbyPerforceSoftware.

PerforceSoftwareassumesnoresponsibilityorliabilityforanyerrorsorinaccuraciesthatmightappearinthisbook.Bydownloadingandusingourprogramsanddocumentsyouagreetotheseterms.

PerforceandInter-FileBranchingaretrademarksofPerforceSoftware.

Allotherbrandsorproductnamesaretrademarksorregisteredtrademarksoftheirrespectivecompaniesororganizations.

AnyadditionalsoftwareincludedwithinPerforceSoftwareislistedin"LicenseStatements"onpage137.

https://www.perforce.com/

Contents

How to use this guide 7Feedback 7

Otherdocumentation 7

Syntaxconventions 7

Whats new in this guide 82018.1release 8

2017.2release 8

Completereplicationforgraphdepotarchives 8HelixVersioningEngineControl(p4dctl)hasmoved 8

Introduction to federated services 9Othertypesoffederatedarchitecture 13

Settingupfederatedservices 13

Generalguidelines 13Authenticatingusers 14Connectingservices 14

Backingupandupgradingservices 15

Backingupservices 16Upgradingservices 16

Configuringcentralizedauthorizationandchangelistservers 17

Centralizedauthorizationserver(P4AUTH) 17Centralizedchangelistserver(P4CHANGE) 20

Verifyingshelvedfiles 20

Helix Server replication 22Systemrequirements 24

Replicationbasics 24

Thep4pullcommand 29Identifyingyourserver 30Serviceusers 31Serveroptionstocontrolmetadataanddepotaccess 33P4TARGET 33Serverstartupcommands 34p4pullvs.p4replicate 34EnablingSSLsupport 35

3

Replicationandprotections 35Howreplicatypeshandlerequests 36

Configuringaread-onlyreplica 37

Masterserversetup 38Creatingthereplica 41Startingthereplica 42Testingthereplica 42Usingthereplica 44Upgradingreplicaservers 45

Configuringaforwardingreplica 45

Configuringthemasterserver 46Configuringtheforwardingreplica 46

Configuringabuildfarmserver 46

Configuringthemasterserver 47Configuringthebuildfarmreplica 48Bindingworkspacestothebuildfarmreplica 49

Configuringareplicawithsharedarchives 50

Filteringmetadataduringreplication 52

Verifyingreplicaintegrity 54

Configuration 55Warnings,notes,andlimitations 57

Commit-edge 59Settingupacommit/edgeconfiguration 60

Createaserviceuseraccountfortheedgeserver 60Createcommitandedgeserverconfigurations 61Createandstarttheedgeserver 63

Shortcutstoconfiguringtheserver 64

Settingglobalclientviews 65

Creatingaclientfromatemplate 66

Migratingfromexistinginstallations 67

Replacingexistingproxiesandreplicas 67Deployingcommitandedgeserversincrementally 68Hardware,sizing,andcapacity 68Migrationscenarios 69

Managingdistributedinstallations 71

Movinguserstoanedgeserver 72

4

Promotingshelvedchangelists 73Lockingandunlockingfiles 74Triggers 75Backupandhighavailability/disasterrecovery(HA/DR)planning 77Otherconsiderations 77

Validation 79

Supporteddeploymentconfigurations 79Backups 79

Helix Broker 80Systemrequirements 80

Installingthebroker 80

Runningthebroker 81

EnablingSSLsupport 82Brokerinformation 82Brokerandprotections 83

P4Brokeroptions 84

Configuringthebroker 85

Formatofbrokerconfigurationfiles 86Specifyinghosts 86Globalsettings 87Commandhandlerspecifications 90Alternateserverdefinitions 95

Usingthebrokerasaload-balancingrouter 96

Configuringthebrokerasarouter 96Routingpolicyandbehavior 97

Helix Proxy 99Systemrequirements 99

InstallingP4P 100

UNIX 100Windows 100

RunningP4P 100

RunningP4PasaWindowsservice 101P4Poptions 101

AdministeringP4P 103

Nobackupsrequired 104StoppingP4P 104

5

UpgradingP4P 104EnablingSSLsupport 104Defendingfromman-in-the-middleattacks 104LocalizingP4P 105Managingdiskspaceconsumption 105DeterminingifyourHelixServerapplicationsareusingtheproxy 105P4Pandprotections 106Determiningifspecificfilesarebeingdeliveredfromtheproxy 107Case-sensitivityissuesandtheproxy 108

Maximizingperformanceimprovement 108

ReducingserverCPUusagebydisablingfilecompression 108NetworktopologiesversusP4P 109Preloadingthecachedirectoryforoptimalinitialperformance 109Distributingdiskspaceconsumption 110

Helix Versioning Engine (p4d) Reference 111Syntax 111

Description 111

ExitStatus 111

Options 111

UsageNotes 117

RelatedCommands 118

Glossary 119License Statements 137

6

How to use this guideThismanualisintendedforadministratorsresponsibleforinstalling,configuring,andmaintainingmultipleinterconnectedorreplicatedPerforceservices.

ThisguideassumesfamiliaritywiththeHelix Versioning Engine Administrator Guide: Fundamentals.

FeedbackHowcanweimprovethismanual?Emailusatmanual@perforce.com.

Other documentationSeehttps://www.perforce.com/support/self-service-resources/documentation.

Syntax conventionsHelixdocumentationusesthefollowingsyntaxconventionstodescribecommandlinesyntax.

Notation Meaningliteral Mustbeusedinthecommandexactlyasshown.

italics Aparameterforwhichyoumustsupplyspecificinformation.Forexample,foraserveridparameter,supplytheIDoftheserver.

[-f] Theenclosedelementsareoptional.Omitthebracketswhenyoucomposethecommand.

... n Repeatsasmuchasneeded:l alias-name[[$(arg1)...

[$(argn)]]=transformation

n Recursiveforalldirectorylevels:

l clone perforce:1666 //depot/main/p4... ~/local-repos/main

l p4 repos -e //gra.../rep...

element1|element2

Eitherelement1orelement2isrequired.

7

http://www.perforce.com/perforce/doc.current/manuals/p4sag/index.htmlmailto:manual@perforce.comhttps://www.perforce.com/support/self-service-resources/documentation

Whats new in this guide

Whats new in this guideThissectionprovidesalistofchangestothisguideforthelatestrelease.ForalistofallnewfunctionalityandmajorbugfixesinthelatestHelixServerrelease,seehttp://www.perforce.com/perforce/doc.current/user/relnotes.txt.

2018.1 releaseTohelpthestandbyserverstayascurrentaspossiblewiththemasterserver,considerusingtheconfigurablethatenableswritingtothedeviceonwhichthestandbyserver'sactivejournalwouldbelocated.Seethementionoftherpl.journalcopy.locationconfigurableat"Configuringaread-onlyreplica"onpage37.

2017.2 release

Complete replication for graph depot archivesEdgeserverssupportsyncingfilecontentfromgraphdepots.Replicationsupportsgraphdepotsthatcontainpackfiles,loosefiles,oramixtureofthepackfilesandloosefiles.

NewcontentcanbepushedbyusingtheGitConnectororcommittedwithp4submitorp4merge.

Forinformationaboutdepotsoftypegraph,see:

n WorkingwithdepotsoftypegraphintheP4CommandReference.

n OverviewintheHelix4GitAdministratorGuide.

Helix Versioning Engine Control (p4dctl) has movedTheappendixnamedHelix Versioning Engine Control (p4dctl),whichwasbothinthisguide(volume2ofthe"HelixVersioningEngineAdministratorGuide")andinthevolume1,"HelixVersioningEngineAdministratorGuide:Fundamentals"(volume1)isnowexclusivelyinvolume1athttps://www.perforce.com/perforce/doc.current/manuals/p4sag/#P4SAG/appendix.p4dctl.html.

8

http://www.perforce.com/perforce/doc.current/user/relnotes.txthttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_submit.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_merge.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_depot.html#Workinghttps://www.perforce.com/perforce/doc.current/manuals/helix-for-git/#Helix4Git/chapter.overview.html%3FTocPath%3DOverview|_____0https://www.perforce.com/perforce/doc.current/manuals/p4sag/#P4SAG/appendix.p4dctl.html

Introduction to federated servicesHelix Versioning Engine Administrator Guide: Fundamentalsexplainshowyoucreate,configure,andmaintainasingleHelixVersioningEngine.Smallorganizationsoftenfindasingleserverisadequatetomeetuserneeds.However,asthebusinessgrowsandusageexpandsinscaleandgeography,manyorganizationsdeployamorepowerfulserver-sideinfrastructure.

9

http://www.perforce.com/perforce/doc.current/manuals/p4sag/index.html

Introduction to federated services

Architecture Advantage Disadvantage"HelixProxy"onpage99 n easyto

install,configure,andmaintain

n improvesperformancebycachingfrequentlytransmittedfilerevisions

n reducesdemandonthePerforceserviceandthenetworkoverwhichitruns

n noneedtobackuptheproxycache

n notoptimalforsyncinglargenumbersofsmallfiles

Tip SeetheKnowledgeBasearticleonProxyPerformance.

10

http://answers.perforce.com/articles/KB/2830http://answers.perforce.com/articles/KB/2830http://answers.perforce.com/articles/KB/2830

Introduction to federated services

Architecture Advantage Disadvantagen especi

allybeneficialwithlargerfiles

"HelixBroker"onpage80 n rule-basedloaddistributionthattypicallyfreesthemasterfrom"readcommands"

n well-suitedforbuildsfromtheread-onlyreplica

n facilitatesswappingtheserversforacheckpointorupgrade

n brokerlayercausessomeoverheadinnetworkperformance

n see"UsingP4Brokertoredirectread-onlycommands"intheKnowledgeBase

11

https://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/introduction.command-and-metadata.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/introduction.command-and-metadata.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/introduction.command-and-metadata.htmlhttp://answers.perforce.com/articles/KB/1253/http://answers.perforce.com/articles/KB/1253/http://answers.perforce.com/articles/KB/1253/http://answers.perforce.com/articles/KB/1253/http://answers.perforce.com/articles/KB/1253/http://answers.perforce.com/articles/KB/1253/http://answers.perforce.com/articles/KB/1253/http://answers.perforce.com/articles/KB/1253/http://answers.perforce.com/articles/KB/1253/http://answers.perforce.com/articles/KB/1253/http://answers.perforce.com/articles/KB/1253/http://answers.perforce.com/articles/KB/1253/

Introduction to federated services

Architecture Advantage DisadvantageForwarding replica n excelle

ntperformanceoverall

n filesandmetadataarelocallycached

n customizablefiltering

n iffullypopulated,canbeawarm standbyforhighavailabilityordisasterrecovery

n "write"commandsareslowerbecauselocalmetadatamustbepulledfromthemaster

n requiresmachineprovisioningandadministration.See"Configuringaforwardingreplica"onpage45.

12

Other types of federated architecture

Architecture Advantage Disadvantage"Commit-edge"onpage59 n best

performanceoverallbecausemostcommandsarelocal

n cannotbeusedasawarmstandby

n requiresmachineprovisioningandadministration,includingbackupsofeachedge

Other types of federated architectureAfederatedarchitecturemightalsoincludeserversdedicatedtocentralizedauthorizationandchangelistnumbering.See"Configuringcentralizedauthorizationandchangelistservers"onpage17.

Setting up federated servicesThissectiondescribessomeoftheissuesthatadministrationmustaddressinsettingupafederatedenvironment.

General guidelines 13Authenticating users 14Connecting services 14

General guidelinesFollowingtheseguidelineswillsimplifytheadministrationandmaintenanceoffederatedenvironments:

n EveryservershouldbeassignedaserverID;itisbestiftheserverIDisthesameastheservername.Usethep4 servercommandtoidentifyeachserverinyournetwork.

13

Authenticating users

n Everyservershouldhaveanassigned(andpreferablyunique)serviceusername.Thissimplifiesthereadingoflogsandprovidesauthenticationandaudittrailsforinter-servercommunication.Assignserviceusersstrongpasswords.Usethep4 servercommandtoassignaserviceusername.

n Enablestructuredloggingonallyourservices.Doingsocangreatlysimplifydebuggingandanalysis,andisalsorequiredinordertousethep4 journaldbchecksumscommandtoverifytheintegrityofareplica.

n Configureeachservertorejectoperationsthatreduceitsdiskspacebelowthelimitsdefinedbythatservicesfilesys.*.minconfigurables.

n Monitortheintegrityofyourreplicasbyusingtheintegrity.csvstructuredserverlogandthep4 journaldbchecksumscommand.See"Verifyingreplicaintegrity"onpage54fordetails.

Authenticating usersUsersmusthaveaticketforeachservertheyaccessinafederatedenvironment.Thebestwaytohandlethisrequirementistosetupasinglelogintothemaster,whichisthenvalidacrossallreplicainstances.Thisisparticularlyusefulwithfailoverconfigurations,whenyouwouldotherwisehavetore-logintothenewmasterserver.

Youcansetupsingle-sign-onauthenticationusingtwoconfigurables:

n Setauth.idtothesamevalueforallserversparticipatinginadistributedconfiguration.

n Enablerpl.forward.login(setto1)foreachreplicaparticipatinginadistributedconfiguration.

Theremightbeaslightlagwhileyouwaitforeachinstancetoreplicatethedb.userrecordfromthetargetserver.

Connecting servicesServicesworkingtogetherinafederatedenvironmentmustbeabletoauthenticateandtrustoneanother.

n WhenusingSSLtosecurelylinkservers,brokers,andproxiestogether,eachlinkinthechainmusttrusttheupstreamlink.

n Itisbestpractice(andmandatoryatsecuritylevel4)touseticket-basedauthenticationinsteadofpassword-basedauthentication.Thismeansthateachserviceuserforeachserverinthechainmustalsohaveavalidloginticketfortheupstreamlinkinthechain.

Managing trust between servicesTheuserthatownstheserver,broker,orproxyprocessistypicallyaserviceuser.Astheadministrator,youmustcreateaP4TRUSTfileonbehalfoftheserviceuserbyusingthep4 trustcommand)thatrecognizesthefingerprintoftheupstreamPerforceservice.

14

Backing up and upgrading services

Bydefault,ausersP4TRUSTfileresidesintheirhomedirectoryas.p4trust.EnsurethattheP4TRUSTvariableiscorrectlysetsothatwhentheuser(oftenascriptorotherautomationtool)thatactuallyinvokesthep4d,p4p,orp4brokerexecutableisabletoreadfilenametowhichP4TRUSTpointsintheinvokingusersenvironment.

FurtherinformationisavailableintheHelix Versioning Engine Administrator Guide: Fundamentals.

Managing tickets between servicesWhenlinkingservers,brokers,andproxiestogether,eachserviceusermustbeavalidserviceuserattheupstreamlink,anditmustbeabletoauthenticatewithavalidloginticket.Followthesestepstosetupserviceauthentication:

1. Ontheupstreamserver,usep4 usertocreateauseroftypeservice,andp4 grouptoassignittoagroupthathasalongorunlimitedtimeout.

Usep4 passwdtoassigntheserviceuserastrongpassword.

2. Onthedownstreamserver,usep4 logintologintothemasterserverasthenewly-createdserviceuser,andtocreatealoginticketfortheserviceuserthatexistsonthedownstreamserver.

3. EnsurethattheP4TICKETvariableiscorrectlysetwhentheuser(oftenascriptorotherautomationtool)thatactuallyinvokesthedownstreamservice,doesso,sothatthedownstreamservicecancorrectlyreadtheticketfileandauthenticateitselfastheserviceusertotheupstreamservice.

Managing SSL key pairsWhenconfiguredtoacceptSSLconnections,allserverprocesses(p4d,p4p,p4broker),requireavalidcertificateandkeypaironstartup.

Theprocessforcreatingakeypairisthesameasitisforanyotherserver:setP4SSLDIRtoavaliddirectorywithvalidpermissions,andusethefollowingcommandstogeneratepairsofprivatekey.txtandcertificate.txtfiles,andmakearecordofthekeysfingerprint.

n Server:usep4d -Gctocreatethekey/certificatepairandp4d -Gftodisplayitsfingerprint.

n Broker:usep4broker -Gctocreatethekey/certificatepairandp4broker -Gftodisplayitsfingerprint.

n Proxy:usep4p -Gctocreatethekey/certificatepairandp4p -Gftodisplayitsfingerprint.

Youcanalsosupplyyourownprivatekeyandcertificate.FurtherinformationisavailableintheHelix Versioning Engine Administrator Guide: Fundamentals.

Backing up and upgrading servicesBackingupandupgradingservicesinafederatedenvironmentinvolvespecialconsiderations.Thissectiondescribestheissuesthatyoumustresolveinthisenvironment.

Backing up services 16Upgrading services 16

15

http://www.perforce.com/perforce/doc.current/manuals/p4sag/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4sag/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4sag/index.html

Backing up services

Backing up servicesHowyoubackupfederatedservicesdependsupontheservicetype:

Broker n storesnodatalocallyn backupitsconfigurationfilemanually

Proxy n requiresnobackupsandautomaticallyrebuildsitscacheofdataiffilesaremissingn containsnologictodetectwhendiskspaceisrunninglow.Periodicallymonitoryour

proxytoensureithassufficientdiskspace.

Server n FollowthebackupproceduresdescribedintheHelix Versioning Engine Administrator Guide: Fundamentals.Ifyouareusinganedge-commitarchitecture,boththecommitserverandtheedgeserversmustbebackedup.Usetheinstructionsgivenin"Backupandhighavailability/disasterrecovery(HA/DR)planning"onpage77.

n Backuprequirementsforreplicasthatarenotedgeserversvarydependingonyoursitesrequirements.

n Considertakingcheckpointsofflinesothatyourusersarenotblockedfromaccessingtheprimaryserverduringlengthycheckpointoperations.SeetheKnowedgeBasearticleson"OfflineCheckpoints"andTakingCheckpointsonEdgeandReplicaServers,especiallythesectionon"DetectingCoordinatedCheckpointCompletion"

n Althoughacheckpoint(p4d -jc)isNOTsupportedonanedgeorreplicaserver,youCANtakeacheckpointdumponanedgeorreplicaserver(p4d -jd).SeetheHelixVersioningEngine(p4d)Reference.

n Maintainingjournals:

l onedgeserversisabestpractice

l onreplicaserversisoptional,andyoucandisablesuchjournalsbyusingp4d -J off

n Youcanhavetriggersfirewhenthejournalisrotatedonanedgeorreplicaserver.See"Triggeringonjournalrotation"inHelix Versioning Engine Administrator Guide: Fundamentals.

n JournalrotationonareplicaoredgeserverbeginsAFTERthemasterhascompleteditsjournalrotation

Upgrading servicesServers,brokers,andproxiesmustbeatthesamereleaselevelinafederatedenvironment.Whenupgradinguseaprocesslikethefollowing:

16

http://www.perforce.com/perforce/doc.current/manuals/p4sag/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4sag/index.htmlhttp://answers.perforce.com/articles/KB/2419/http://answers.perforce.com/articles/KB/15188http://answers.perforce.com/articles/KB/15188https://www.perforce.com/perforce/doc.current/manuals/p4sag/#P4SAG/appendix.p4d.htmlhttps://www.perforce.com/perforce/doc.current/manuals/p4sag/#P4SAG/scripting.triggers.journal.html

Configuring centralized authorization and changelist servers

1. Shutdownthefurthest-upstreamserviceorcommitserverandpermitthesystemtoquiesce.

2. Upgradedownstreamservicesfirst,startingwiththereplicathatisfurthestdownstream,workingupstreamtowardsthemasterorcommitserver.

3. Keepdownstreamservicesstoppeduntiltheserverimmediatelyupstreamhasbeenupgraded.

Configuring centralized authorization and changelist serversTherearecaseswhereratherthanusingfederatedservicesyouwanttouseacollectionofserversthathaveashareduserbase.Inthissituation,youprobablywanttousespecializedserverstosimplifyuserauthenticationandtoguaranteeuniquechangelistnumbersacrosstheorganization.Thefollowingsubsectionsexplainhowyoucreateandusetheseservers:P4AUTHforcentralizedauthenticationandP4CHANGEtogenerateuniquechangelistnumbers.

Centralized authorization server (P4AUTH) 17Centralized changelist server (P4CHANGE) 20

Centralized authorization server (P4AUTH)IfyouarerunningmultipleHelixServers,youcanconfigurethemtoretrieveprotectionsandlicensingdatafromacentralized authorization server.Byusingacentralizedserver,youarefreedfromthenecessityofensuringthatallyourserverscontainthesameusersandprotectionsentries.

Note Whenusingacentralizedauthenticationserver,allouterserversmustbeatthesame(ornewer)releaselevelasthecentralserver.

Ifauserdoesnotexistonthecentralauthorizationserver,thatuserdoesnotappeartoexistontheouterserver.Ifauserexistsonboththecentralauthorizationserverandtheouterserver,themostpermissiveprotectionsofthetwolinesoftheprotectionstableareassignedtotheuser.

YoucanuseanyexistingHelixVersioningEngineinyourorganizationasyourcentralauthorizationserver.Thelicensefileforthecentralauthorizationservermustbevalid,asitgovernsthenumberoflicensedusersthatarepermittedtoexistonouterservers.ToconfigureaHelixVersioningEnginetouseacentralauthorizationserver,setP4AUTHbeforestartingtheserver,orspecifyitonthecommandlinewhenyoustarttheserver.

Ifyourserverismakinguseofacentralizedauthorizationserver,thefollowinglinewillappearintheoutputofp4 info:

...

Authorization Server: [protocol:]host:port

Where[protocol:]host:portreferstotheprotocol,host,andportnumberofthecentralauthorizationserver.See"Specifyinghosts"onpage86.

17

Centralized authorization server (P4AUTH)

Inthefollowingexample,anouterserver(namedserver2)isconfiguredtouseacentralauthorizationserver(namedcentral).Theouterserverlistensforuserrequestsonport1999andreliesonthecentralserversdataforuser,group,protection,review,andlicensinginformation.Italsojoinstheprotectiontablefromtheserveratcentral:1666toitsownprotectionstable.

Forexample:

$ p4d -In server2 -a central:1666 -p 1999

Note OnWindows,configuretheouterserverwithp4 set -Sasfollows:

C:\> p4 set -S "Outer Server" P4NAME=server2

C:\> p4 set -S "Outer Server" P4AUTH=central:1666

C:\> p4 set -S "Outer Server" P4PORT=1999

Whenyouconfigureacentralauthorizationserver,outerserversforwardthefollowingcommandstothecentralserverforprocessing:

Command Forwarded to auth server?

Notes

p4 group Yes Localgroupdataisderivedfromthecentralserver.

p4 groups

Yes Localgroupdataisderivedfromthecentralserver.

p4 license

Yes Licenselimitsarederivedfromthecentralserver.Licenseupdatesareforwardedtothecentralserver.

p4 passwd

Yes Passwordsettingsarestoredon,andmustmeetthesecuritylevelrequirementsof,thecentralserver.

p4 review

No Thedefaultusernamedremotemusthaveaccesstothecentralserver.However,bestpracticeistocreate"Serviceusers"onpage31andnotusethedefaultusernamedremote.SeeRestrictingaccesstoremotedepotsinHelixVersioningEngineAdministratorGuide:Fundamentals.

p4 reviews

No Thedefaultusernamedremotemusthaveaccesstothecentralserver.However,bestpracticeistocreate"Serviceusers"onpage31andnotusethedefaultusernamedremote.SeeRestrictingaccesstoremotedepotsinHelixVersioningEngineAdministratorGuide:Fundamentals.

p4 user Yes Localuserdataisderivedfromthecentralserver.

18

https://www.perforce.com/perforce/doc.current/manuals/p4sag/#P4SAG/superuser.remote_depots.code_drops.htmlhttps://www.perforce.com/perforce/doc.current/manuals/p4sag/https://www.perforce.com/perforce/doc.current/manuals/p4sag/https://www.perforce.com/perforce/doc.current/manuals/p4sag/#P4SAG/superuser.remote_depots.code_drops.htmlhttps://www.perforce.com/perforce/doc.current/manuals/p4sag/https://www.perforce.com/perforce/doc.current/manuals/p4sag/

Centralized authorization server (P4AUTH)

Command Forwarded to auth server?

Notes

p4 users Yes Localuserdataisderivedfromthecentralserver.

p4 protect

No Thelocalserversprotectionstableisdisplayediftheuserisauthorized(asdefinedbythecombinedprotectiontables)toeditit.

p4 protects

Yes Protectionsarederivedfromthecentralserversprotectiontableasappendedtotheouterserversprotectiontable.

p4 login Yes Commandisforwardedtothecentralserverforticketgeneration.

p4 logout

Yes Commandisforwardedtothecentralserverforticketinvalidation.

Limitations and notesn AllserversthatuseP4AUTHmusthavethesameUnicodesettingasthecentralauthorization

server.

n SettingP4AUTHbymeansofap4 configure set P4AUTH=[protocol:]server:portcommandrequiresarestartoftheouterserver.

IfyouneedtosetP4AUTHforareplica,usethefollowingsyntax:

p4 configure set ServerName#P4AUTH=[protocol:]server:port

n IfyouhavesetP4AUTH,nowarningwillbegivenifyoudeleteauserwhohasanopenfileorclient.

n Toensurethatp4 reviewandp4 reviewsworkcorrectly,youmustenableremotedepotaccessfortheserviceuser(or,ifnoserviceuserisspecified,forausernamedremote)onthecentralserver.

Note:Thereisnoremotetypeuser;thereisaspecialusernamedremotethatisusedtodefineprotectionsforaremotedepot.

n Toensurethattheauthenticationservercorrectlydistinguishesforwardedcommandsfromcommandsissuedbytrusted,directly-connectedusers,youmustdefineanyIP-basedprotectionentriesinthePerforceservicebyprependingthestringproxy-tothe[protocol:]host:portdefinition.

Important Beforeyouprependthestringproxy-totheworkstationsIPaddress,makesurethatabrokerorproxyisinplace.

n Protectionsfornon-forwardedcommandsareenforcedbytheouterserverandusetheplainclientIPaddress,eveniftheprotectionsarederivedfromlinesinthecentralserversprotectionstable.

19

Centralized changelist server (P4CHANGE)

Centralized changelist server (P4CHANGE)Bydefault,HelixServersdonotcoordinatethenumberingofchangelists.EachHelixVersioningEnginenumbersitschangelistsindependently.Ifyouarerunningmultipleservers,youcanconfigureyourserverstorefertoacentralized changelist serverfromwhichtoobtainchangelistnumbers.Doingsoensuresthatchangelistnumbersareuniqueacrossyourorganization,regardlessoftheservertowhichtheyaresubmitted.

Note Whenusingacentralizedchangelistserver,allouterserversmustbeatthesame(ornewer)releaselevelasthecentralserver.

ToconfigureHelixServertouseacentralizedchangelistserver,setP4CHANGEbeforestartingthesecondserver,orspecifyitonthep4dcommandlinewiththe-goption:

$ p4d -In server2 -g central:1666 -p 1999

Note OnWindows,configuretheouterserverwithp4 set -Sasfollows:

C:\> p4 set -S "Outer Server" P4NAME=server2

C:\> p4 set -S "Outer Server" P4CHANGE=central:1666

C:\> p4 set -S "Outer Server" P4PORT=1999

Inthisexample,theouterserver(namedserver2)isconfiguredtouseacentralizedchangelistserver(namedcentral).Wheneverauseroftheouterservermustassignachangelistnumber(thatis,whenausercreatesapendingchangelistorsubmitsone),thecentralizedserversnextavailablechangelistnumberisusedinstead.

Thereisnolimitonthenumberofserversthatcanrefertoacentralizedchangelistserver.Thisconfigurationhasnoeffectontheoutputofthep4 changescommand;p4 changeslistsonlychangelistsfromthecurrentlyconnectedserver,regardlessofwhetheritgeneratesitsownchangelistnumbersorreliesonacentralizedchangelistserver.

Ifyourserverismakinguseofacentralizedchangelistserver,thefollowinglinewillappearintheoutputofp4 info:

...

Changelist Server: [protocol:]host:port

Where[protocol:]host:portreferstotheprotocol,host,andportnumberofthecentralizedchangelistserver.

Verifying shelved filesTheverificationofshelvedfilesletsyouknowwhetheryourshelvedarchiveshavebeenlostordamaged.

20

Verifying shelved files

Ifashelfislocaltoaspecificedgeserver,youmustissuethep4 verify -Scommandontheedgeserverwheretheshelfwascreated.Iftheshelfwaspromoted,runthep4 verify -Sonthecommitserver.

Youmayalsorunthep4 verify -S tcommandonareplicatorequestre-transferofashelvedarchivethatismissingorbad.Re-transferringashelvedarchivefromthemasteronlyworksforshelvedarchivesthatarepresentonthemaster;thatis,forashelfthatwasoriginallycreatedonthemasterorthatwaspromotedifitwascreatedonanedgeserver.

21

Helix Server replicationThistopicassumesyouhavereadthe"Introductiontofederatedservices"onpage9.

ReplicationistheduplicationofserverdatafromoneHelixVersioningEnginetoanotherHelixVersioningEngine,ideallyinrealtime.Youcanusereplicationto:

n Providewarmstandbyservers

Areplicaservercanfunctionasanup-to-datewarmstandbysystemtobeusedifthemasterserverfails.Suchareplicaserverrequiresthatbothservermetadataandversionedfilesarereplicated.

n Reduceloadanddowntimeonaprimaryserver

Long-runningqueriesandreports,builds,andcheckpointscanberunagainstareplicaserver,reducinglockcontention.Forcheckpointsandsomereportingtasks,onlymetadataneedstobereplicated.Forreportingandbuilds,replicaserversneedaccesstobothmetadataandversionedfiles.

n Providesupportforbuildfarms

Areplicawithalocal(non-replicated)storageforclientworkspaces(andtheirrespectivehavelists)iscapableofrunningasabuildfarm.

n Forwardwriterequeststoacentralserver

Aforwardingreplicaholdsareadablecacheofbothversionedfilesandmetadata,andforwardscommandsthatwritemetadataorfilecontenttowardsacentralserver.AforwardingreplicaoffersablendofthefunctionalityoftheHelixProxywiththeimprovedperformanceofareplica.(See"Configuringaforwardingreplica"onpage45.)

Combinedwithacentralizedauthorizationserver(see"Centralizedauthorizationserver(P4AUTH)"onpage17),HelixServeradministratorscanconfiguretheHelixBroker(see"HelixBroker"onpage80)toredirectcommandstoreplicaserverstobalanceloadefficientlyacrossanarbitrarynumberofreplicaservers.

Note Mostreplicaconfigurationsareintendedforreadingofdata.Ifyourequirereadandwriteaccesstoaremoteserver,useaforwardingreplica,adistributedPerforceservice,ortheHelixProxy.See"Configuringaforwardingreplica"onpage45,"Commit-edge"onpage59and"HelixProxy"onpage99.

Tip ThefollowingKnowledgeBasearticlescontainvaluableinformation:

22

Helix Server replication

n InstallingaHelixReplicaServer

n CheckpointsinaDistributedHelixenvironment

n TakingCheckpointsonEdgeandReplicaServers

n ConfiguringCheckpointandRotatedJournallocationinDistributedHelixEnvironments

n Inspectingreplicationprogress

n VerifyingReplicaIntegrity

n Howtoreseedareplicaserver

n EdgeServerMetaDataRecovery

n Failingovertoareplicaserver

n EdgeServers(differencesinbehaviorofcertaincommands)

System requirements 24Replication basics 24Thep4pullcommand 29Identifyingyourserver 30Serviceusers 31Serveroptionstocontrolmetadataanddepotaccess 33P4TARGET 33Serverstartupcommands 34p4pullvs.p4replicate 34EnablingSSLsupport 35Replicationandprotections 35

How replica types handle requests 36Configuring a read-only replica 37Masterserversetup 38Creatingthereplica 41Startingthereplica 42Testingthereplica 42Usingthereplica 44Upgradingreplicaservers 45

Configuring a forwarding replica 45Configuringthemasterserver 46Configuringtheforwardingreplica 46

Configuring a build farm server 46Configuringthemasterserver 47Configuringthebuildfarmreplica 48Bindingworkspacestothebuildfarmreplica 49

Configuring a replica with shared archives 50Filtering metadata during replication 52Verifying replica integrity 54Configuration 55

Warnings, notes, and limitations 57

23

http://answers.perforce.com/articles/KB/1260/http://answers.perforce.com/articles/KB/3865http://answers.perforce.com/articles/KB/15188http://answers.perforce.com/articles/KB/2505http://answers.perforce.com/articles/KB/14798http://answers.perforce.com/articles/KB/3867http://answers.perforce.com/articles/KB/2520http://answers.perforce.com/articles/KB/12127http://answers.perforce.com/articles/KB/2495/http://answers.perforce.com/articles/KB/3847

System requirements

System requirementsn Replicaserversshouldbeatthesamereleaseasthemasterserver.

Important See"Upgradingreplicaservers"onpage45andtheKnowledgeBasearticle,"UpgradingReplicaServers".

n ReplicaserversmusthavethesameUnicodesettingasthemasterserver.

n Replicaserversmustbehostedonafilesystemwiththesamecase-sensitivitybehaviorasthemasterserversfilesystem.

n p4 pull(whenreplicatingmetadata)doesnotreadcompressedjournals.Themasterservermustnotcompressjournalsuntilthereplicaserverhasfetchedalljournalrecordsfromolderjournals.Onlyonemetadata-updatingp4 pullthreadcanbeactiveatonetime.

n Thereplicaserverdoesnotneedaduplicatelicensefile.

n Themasterandreplicaserversmusthavethesametimezonesetting.

Note OnWindows,thetimezonesettingissystem-wide.

OnUNIX,thetimezonesettingiscontrolledbytheTZenvironmentvariableatthetimethereplicaserverisstarted.

Replication basicsReplicationofHelixServersdependsuponseveralcommandsandconfigurables:

Command or Feature

Typical use case

p4 pull Acommandthatcanreplicatebothmetadataandversionedfiles,andreportdiagnosticinformationaboutpendingcontenttransfers.

Areplicaservercanrunmultiplep4 pullcommandsagainstthesamemasterserver.Toreplicatebothmetadataandfilecontents,youmustruntwop4 pullthreadssimultaneously:one(andonlyone)p4 pull(withoutthe-uoption)threadtoreplicatethemasterserversmetadata,andone(ormore)p4 pull -uthreadstoreplicateupdatestotheserversversionedfiles.

24

http://answers.perforce.com/articles/KB/2515/http://answers.perforce.com/articles/KB/2515/https://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_pull.html

Replication basics

Command or Feature

Typical use case

p4 configure Aconfigurationmechanismthatsupportsmultipleservers.

Becausep4 configurestoresitsdataonthemasterserver,allreplicaserversautomaticallypickupanychangesyoumake.

p4 server Aconfigurationmechanismthatdefinesaserverintermsofitsofferedservices.Inordertobeeffective,theServerID:fieldinthep4 serverformmustcorrespondwiththeserversserver.idfileasdefinedbythep4 serveridcommand.

p4 serverid AcommandtosetordisplaytheuniqueidentifierforaHelixVersioningEngine.Onstartup,aservertakesitsIDfromthecontentsofaserver.idfileinitsrootdirectoryandexaminesthecorrespondingspecdefinedbythep4 servercommand.

p4 verify -t Causesthereplicatoscheduleatransferofthecontentsofanydamagedormissingrevisions.

ThecommandreportsBAD!orMISSING!fileswith(transfer scheduled)attheendoftheline.

Forthetransfertoworkonareplicawithlbr.replication=cache,thereplicashouldhaveoneormorep4 pull -uthreadsconfigured(perhapsalsousingthe--batch=Nflag.)

Servernames

P4NAMEp4d -In name

HelixServerscanbeidentifiedandconfiguredbyname.

Whenyouusep4 configureonyourmasterserver,youcanspecifydifferentsetsofconfigurablesforeachnamedserver.Eachnamedserver,uponstartup,referstoitsownsetofconfigurables,andignoresconfigurablessetforotherservers.

Serviceusers

p4d -u svcuser

Anewtypeofuserintendedforauthenticationofserver-to-servercommunications.ServiceusershaveextremelylimitedaccesstothedepotanddonotconsumeHelixServerlicenses.

Tomakelogseasiertoread,createoneserviceuseronyourmasterserverforeachreplicaorproxyinyournetworkofHelixServers.

Metadataaccess

p4d -M readonlydb.replication

Replicaserverscanbeconfiguredtoautomaticallyrejectusercommandsthatattempttomodifymetadata(db.*files).

In-M readonlymode,theHelixVersioningEnginedeniesanycommandthatattemptstowritetoservermetadata.Inthismode,acommandsuchasp4 sync(whichupdatestheservershavelist)isrejected,butp4 sync -p(whichpopulatesaclientworkspacewithoutupdatingtheservershavelist)isaccepted.

25

Replication basics

Command or Feature

Typical use case

Metadatafiltering Replicaserverscanbeconfiguredtofilterin(orout)dataonclientworkspacesandfilerevisions.

Youcanusethe-P serverIdoptionwiththep4dcommandtocreateafilteredcheckpointbasedonaserverId.

Youcanusethe-T tableexcludelistoptionwithp4 pulltoexplicitlyfilteroutupdatestoentiredatabasetables.

UsingtheClientDataFilter:,RevisionDataFilter:,andArchiveDataFilter:fieldsofthep4 serverformcanprovideyouwithfarmorefine-grainedcontroloverwhatdataisreplicated.Usethe-P serveridoptionwithp4 pull,andspecifytheName:oftheserverwhosep4 serverspecholdsthedesiredsetoffilterpatterns.

26

Replication basics

Command or Feature

Typical use case

Depotfileaccess

p4d -D readonlyp4d -D sharedp4d -D ondemandp4d -D cachep4d -D nonelbr.replication

Replicaserverscanbeconfiguredtoautomaticallyrejectusercommandsthatattempttomodifyarchiveddepotfiles(thelibrary).

n In-D readonlymode,theHelixVersioningEngineacceptscommandsthatreaddepotfiles,butdeniescommandsthatwritetothem.Inthismode,p4 describecandisplaythediffsassociatedwithachangelist,butp4 submitisrejected.

n In-D ondemandmode,or-D sharedmode(thetwoaresynonymous)theHelixServeracceptscommandsthatreadmetadata,butdoesnottransfernewfilesnorremovepurgedfilesfromthemaster.(p4 pull -uandp4 verify -t,whichwouldotherwisetransferarchivefiles,aredisabled.)Ifafileisnotpresentinthearchives,commandsthatreferencethatfilewillfail.

Thismodemustbeusedwhenareplicadirectlysharesthesamephysicalarchivesasthetarget,whetherbyrunningonthesamemachineorvianetworksharing.Thismodecanalsobeusedwhenanexternalarchivesynchronizationtechnique,suchasrsyncisusedforarchives.

n In-D cachemode,theHelixVersioningEnginepermitscommandsthatreferencefilecontent,butdoesnotautomaticallytransfernewfiles.Filesthatarepurgedfromthetargetareremovedfromthereplicawhenthepurgeoperationisreplicated.Ifafileisnotpresentinthearchives,thereplicawillretrieveitfromthetargetserver.

n In-D nonemode,theHelixVersioningEnginedeniesanycommandthataccessestheversionedfilesthatmakeupthedepot.Inthismode,acommandsuchasp4 describe changenumisrejectedbecausethediffsdisplayedwithachangelistrequireaccesstotheversionedfiles,butp4 describe -s changenum(whichdescribesachangelistwithoutreferringtothedepotfilesinordertogenerateasetofdiffs)isaccepted.

Theseoptionscanalsobesetusinglbr.replication.*configurables,describedinthe"Configurables"appendixoftheP4 Command Reference.

27

http://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html

Replication basics

Command or Feature

Typical use case

Targetserver

P4TARGET

AswiththeHelixProxy,youcanuseP4TARGETtospecifythemasterserveroranotherreplicaservertowhichareplicaserverpointswhenretrievingitsdata.

YoucansetP4TARGETexplicitly,oryoucanusep4 configuretosetaP4TARGETforeachnamedreplicaserver.

AreplicaserverwithP4TARGETsetmusthaveboththe-Mand-Doptions,ortheirequivalentdb.replicationandlbr.replicationconfigurables,correctlyspecified.

Startupcommands

startup.1

Usethestartup.n(wherenisaninteger)configurabletoautomaticallyspawnmultiplep4 pullprocessesonstartup.

Statefile

statefile

Replicaserverstrackthemostrecentjournalpositioninasmalltextfilethatholdsabyteoffset.Whenyoustopeitherthemasterserverorareplicaserver,themostrecentjournalpositionisrecordedonthereplicainthestatefile.

Uponrestart,thereplicareadsthestatefileandpicksupwhereitleftoff;donotalterthisfileoritscontents.(Whenthestatefileiswritten,atemporaryfileisusedandmovedintoplace,whichshouldpreservetheexistingstatefileifsomethinggoeswrongwhenupdatingit.Ifthestatefileshouldbeemptyormissing,thereplicaserverwillrefetchfromthestartofitslastusedjournalposition.)

Bydefault,thestatefileisnamedstateanditresidesinthereplicaserversrootdirectory.Youcanspecifyadifferentfilenamebysettingthestatefileconfigurable.

P4Broker TheHelixBrokercanbeusedforloadbalancing,commandredirection,andmore.See"HelixBroker"onpage80fordetails.

Warning Replicationrequiresuncompressedjournals.Startingthemasterusingthep4d -jc -zcommandbreaksreplication;usethe-Zflaginsteadtopreventjournalsfrombeingcompressed.

The p4 pull command 29Identifying your server 30Service users 31Server options to control metadata and depot access 33P4TARGET 33Server startup commands 34p4 pull vs. p4 replicate 34Enabling SSL support 35Replication and protections 35

28

The p4 pull command

The p4 pull commandThep4 pullcommandprovidesthemostgeneralsolutionforreplication.Usep4 pulltoconfigureareplicaserverthat:

n replicatesversionedfiles(the,vfilesthatcontainthedeltasthatareproducedwhennewversionsaresubmitted)unidirectionallyfromamasterserver.

n replicatesservermetadata(theinformationcontainedinthedb.*files)unidirectionallyfromamasterserver.

n usesthestartup.nconfigurabletoautomaticallyspawnasmanyp4 pullprocessesasrequired.

Acommonconfigurationforawarmstandbyserverisoneinwhichone(andonlyone)p4 pullprocessisspawnedtoreplicatethemasterserversmetadata,andmultiplep4 pull -uprocessesarespawnedtoruninparallel,andcontinuallyupdatethereplicascopyofthemasterserversversionedfiles.

n Thestartup.nconfigurablesareprocessedsequentially.Processingstopsatthefirstgapinthenumericalsequence.Anycommandsafteragapareignored.

Althoughyoucanrunp4 pullfromthecommandlinefortestinganddebuggingpurposes,itsmostusefulwhencontrolledbythestartup.nconfigurables,andinconjunctionwithnamedservers,serviceusers,andcentrally-managedconfigurations.

The--batchoptiontothep4 pullspecifiesthenumberoffilesapullthreadshouldprocessinasinglerequest.Thedefaultvalueof1isusuallyadequate.Forhigh-latencyconfigurations,alargervaluemightimprovearchivetransferspeedforlargenumbersofsmallfiles.(Useofthisoptionrequiresthatbothmasterandreplicabeatversion2015.2orhigher.)

Settingtherpl.compressconfigurableallowsyoutocompressjournalrecorddatathatistransmittedusingp4 pull.

Note Ifyouarerunningareplicawithmonitoringenabledandyouhavenotconfiguredthemonitortabletobedisk-resident,youcanrunthefollowingcommandtogetmorepreciseinformationaboutwhatpullthreadsaredoing.(Remembertosetmonitor.lsof).

$ p4 monitor show -sB -la -L

Commandoutputwouldlooklikethis:

31701 B uservice-edge3 00:07:24 pull sleeping 1000 ms

[server.locks/replica/49,d/pull(W)]

Thepossiblestatusmessagesare:

29

Identifying your server

For journal records For pulling archivesscanned NNNN records sleeping

applied NNNN records running

rotating journal

Identifying your serverGivingyourserverauniqueIDpermitsmostoftheserverconfigurationdatatobestoredintheHelixVersioningEngine.Thisisanalternativetousingstartupoptionsorenvironmentvariables.AuniqueserverIDisessentialforconfiguringreplicationbecausep4configuresettingsarereplicatedfromthemasterservertothereplicasalongwithothermetadata.

Configuringthefollowingserversrequiretheuseofaserverspec:

Type Description

Commitserver centralserverinadistributedinstallation

Edgeserver nodeinadistributedinstallation

Buildserver replicathatsupportsbuildfarmintegration

Depotmaster commitserverwithautomatedfailover

Depotstandby standbyreplicaofthedepotmaster

Standbyserver read-onlyreplicathatusesp4journalcopy

Forwardingstandby forwardingreplicathatusesp4journalcopy

Thep4serveridcommandcreatesasmalltextfilenamedserver.idintherootdirectoryoftheserver.Theserverexecutable,p4d,canalsocreatethisserver.idfile:

p4d -r $P4ROOT -xD

Tip n Toseetheserverid,usep4d -xDorthep4serveridcommand

n Iftheresponseis"Server does not yet have a server ID",settheserverIDwithp4d -xD myServer

n TochangeanexistingserverID,deletetheserver.idfile,thensettheserverID

Youcanusethep4servercommandto:

30

https://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_configure.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_journalcopy.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_journalcopy.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_serverid.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_serverid.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_server.html

Service users

n defineaspecificationforeachoftheserversknowntoyourinstallation

n createauniqueserverIDthatcanbepassedtothep4serveridcommand,andtodefinetheservicesofferedbyanyserverthat,uponstartup,readsthatserverIDfromaserver.idfile

Forexample,youcansetyourmasterserveridtomyMasterandthereplicaidtomyReplica:

p4 -p svrA.company.com:11111 serverid myMaster

Server myMaster saved.

p4 -p svrB.company.com:22222 serverid myReplica

Server myReplica saved.

Youcanusep4configureonthemasterinstancetocontrolsettingsonboththemasterandthereplicabecauseconfigurationsettingsarepartofthereplicatedmetadataofaHelixServerserver.

Forexample,ifyouissuethefollowingcommandsonthemasterserver:

$ p4 -p svrA.company.com:11111 configure set myMaster#monitor=2

$ p4 -p svrA.company.com:11111 configure set myReplica#monitor=1

thetwoservershavedifferentmonitoringlevelsaftertheconfigurationdatahasbeenreplicated.Therefore,ifyourunp4monitorshowagainstthemasterserver,youseebothactiveandidleprocessesbecausethemonitorconfigurableissetto2forthemasterserver.Incontrast,ifyourunp4monitorshowagainstthereplica,youseeonlyactiveprocessesbecause1isthemonitorsetting.

Amasterandeachreplicaislikelytohaveitsownjournalandcheckpointfiles.Toensuretheirprefixesareunique,usethejournalPrefixconfigurableforeachnamedserver:

$ p4 -p svrA.company.com:11111 configure set

myMaster#journalPrefix=/p4/ckps/myMaster

For server 'myMaster', configuration variable 'journalPrefix' set

to '/p4/ckps/myMaster'

$ p4 -p svrA.company.com:11111 configure set

myReplica#journalPrefix=/p4/ckps/myReplica

For server 'myReplica', configuration variable 'journalPrefix'

set to '/p4/ckps/myReplica'

Service usersTherearethreetypesofHelixServerusers:standardusers,operatorusers,andserviceusers.AstandarduserisatraditionaluserofHelixServer,anoperatoruserisintendedforhumanorautomatedsystemadministrators,andaserviceuserisusedforserver-to-serverauthentication,aspartofthereplicationprocess.

Serviceusersareusefulforremotedepotsinsingle-serverenvironments,butarerequiredformulti-serveranddistributedenvironments.

31

https://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_serverid.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_configure.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_monitor.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/configurables.configurables.html#monitorhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_monitor.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/configurables.configurables.html#journalPrefix

Service users

Createaserviceuserforeachmaster,replica,orproxyserverthatyoucontrol.Doingsogreatlysimplifiesthetaskofinterpretingyourserverlogs.Serviceuserscanalsohelpyouimprovesecurity,byrequiringthatyouredgeserversandotherreplicashavevalidloginticketsbeforetheycancommunicatewiththemasterorcommitserver.ServiceusersdonotconsumeHelixServerlicenses.

Aserviceusercanrunonlythefollowingcommands:

n p4 dbschema

n p4 export

n p4 login

n p4 logout

n p4 passwd

n p4 info

n p4 user

Tocreateaserviceuser,runthecommand:

p4 user -f service1

Thestandarduserformisdisplayed.EnteranewlinetosetthenewusersType:tobeservice;forexample:

User: service1

Email: services@example.com

FullName: Service User for Replica Server 1

Type: service

Bydefault,theoutputofp4 usersomitsserviceusers.Toincludeserviceusers,runp4 users -a.

Tickets and timeouts for service usersAnewly-createdserviceuserthatisnotamemberofanygroupsissubjecttothedefaulttickettimeoutof12hours.Toavoidissuesthatarisewhenaserviceusersticketceasestobevalid,createagroupforyourserviceusersthatfeaturesanextremelylongtimeout,ortounlimited.Onthemasterserver,issuethefollowingcommand:

p4 group service_users

Addservice1tothelistofUsers:inthegroup,andsettheTimeout:andPasswordTimeout:valuestoalargevalueortounlimited.

Group: service_users

Timeout: unlimited

PasswordTimeout: unlimited

Subgroups:

Owners:

32

Server options to control metadata and depot access

Users:

service1

Important Serviceusersmusthaveaticketcreatedwiththep4 loginforreplicationtowork.

Permissions for service usersOnthemasterserver,usep4 protecttogranttheserviceusersuperpermission.Serviceusersaretightlyrestrictedinthecommandstheycanrun,sograntingthemsuperpermissionissafe.

Server options to control metadata and depot accessWhenyoustartareplicathatpointstoamasterserverwithP4TARGET,youmustspecifyboththe-M(metadataaccess)anda-D(depotaccess)options,orsettheconfigurablesdb.replication(accesstometadata)andlbr.replication(accessthedepotslibraryofversionedfiles)tocontrolwhichHelixServercommandsarepermittedorrejectedbythereplicaserver.

P4TARGETSetP4TARGETtothethefully-qualifieddomainnameorIPaddressofthemasterserverfromwhichareplicaserveristoretrieveitsdata.YoucansetP4TARGETexplicitly,specifyitonthep4dcommandlinewiththe-t protocol:host:portoption,oryoucanusep4 configuretosetaP4TARGETforeachnamedreplicaserver.Seethetablebelowfortheavailableprotocoloptions.

Ifyouspecifyatarget,p4dexaminesitsconfigurationforstartup.ncommands:ifnovalidp4 pullcommandsarefound,p4drunsandwaitsfortheusertomanuallystartap4 pullcommand.Ifyouomitatarget,p4dassumestheexistenceofanexternalmetadatareplicationsourcesuchasp4 replicate.See"p4pullvs.p4replicate"onthefacingpagefordetails.

Protocol Behavior

Usetcp4:behavior,butiftheaddressisnumericandcontainstwoormorecolons,assumetcp6:.Ifthenet.rfc3484configurableisset,allowtheOStodeterminewhichtransportisused.

tcp: Usetcp4:behavior,butiftheaddressisnumericandcontainstwoormorecolons,assumetcp6:.Ifthenet.rfc3484configurableisset,allowtheOStodeterminewhichtransportisused.

tcp4: Listenon/connecttoanIPv4address/portonly.

tcp6: Listenon/connecttoanIPv6address/portonly.

tcp46: Attempttolistenon/connecttoanIPv4address/port.Ifthisfails,tryIPv6.

33

Server startup commands

Protocol Behaviortcp64: Attempttolistenon/connecttoanIPv6address/port.Ifthisfails,tryIPv4.

ssl: Usessl4:behavior,butiftheaddressisnumericandcontainstwoormorecolons,assumessl6:.Ifthenet.rfc3484configurableisset,allowtheOStodeterminewhichtransportisused.

ssl4: Listenon/connecttoanIPv4address/portonly,usingSSLencryption.

ssl6: Listenon/connecttoanIPv6address/portonly,usingSSLencryption.

ssl46: Attempttolistenon/connecttoanIPv4address/port.Ifthisfails,tryIPv6.Afterconnecting,requireSSLencryption.

ssl64: Attempttolistenon/connecttoanIPv6address/port.Ifthisfails,tryIPv4.Afterconnecting,requireSSLencryption.

P4TARGETcanbethehosts'hostnameoritsIPaddress;bothIPv4andIPv6addressesaresupported.Forthelistensetting,youcanusethe*wildcardtorefertoallIPaddresses,butonlywhenyouarenotusingCIDRnotation.

Ifyouusethe*wildcardwithanIPv6address,youmustenclosetheentireIPv6addressinsquarebrackets.Forexample,[2001:db8:1:2:*]isequivalentto[2001:db8:1:2::]/64.BestpracticeistouseCIDRnotation,surroundIPv6addresseswithsquarebrackets,andtoavoidthe*wildcard.

Server startup commandsYoucanconfigureHelixServertoautomaticallyruncommandsatstartupusingthep4 configureasfollows:

p4 configure set "servername#startup.n=command"

Wherenrepresentstheorderinwhichthecommandsareexecuted:thecommandspecifiedforstartup.1runsfirst,thenthecommandforstartup.2,andsoon.Theonlyvalidstartupcommandisp4 pull.

p4 pull vs. p4 replicateHelixServeralsosupportsamorelimitedformofreplicationbasedonthep4replicatecommand.Thiscommanddoesnotreplicatefilecontent,butsupportsfilteringofmetadataonaper-tablebasis.

34

https://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_replicate.html

Enabling SSL support

Enabling SSL supportToencrypttheconnectionbetweenareplicaserveranditsendusers,thereplicamusthaveitsownvalidprivatekeyandcertificatepairinthedirectoryspecifiedbyitsP4SSLDIRenvironmentvariable.Certificateandkeygenerationandmanagementforreplicaserversworksthesameasitdoesforthe(master)server.See"EnablingSSLsupport"onpage82.Theusers'HelixServerapplicationsmustbeconfiguredtotrustthefingerprintofthereplicaserver.

Toencrypttheconnectionbetweenareplicaserveranditsmaster,thereplicamustbeconfiguredsoastotrustthefingerprintofthemasterserver.Thatis,theuserthatrunsthereplicap4d(typicallyaserviceuser)mustcreateaP4TRUSTfile(usingp4 trust)thatrecognizesthefingerprintofthemasterHelixVersioningEngine.

TheP4TRUSTvariablespecifiesthepathtotheSSLtrustfile.Youmustsetthisenvironmentvariableinthefollowingcases:

n forareplicathatneedstoconnecttoanSSL-enabledmasterserver,or

n foranedgeserverthatneedstoconnecttoanSSL-enabledcommitserver.

Replication and protectionsToapplytheIPaddressofareplicausersworkstationagainsttheprotectionstable,prependthestringproxy-totheworkstationsIPaddress.

Important Beforeyouprependthestringproxy-totheworkstationsIPaddress,makesurethatabrokerorproxyisinplace.

Forinstance,consideranorganizationwitharemotedevelopmentsitewithworkstationsonasubnetof192.168.10.0/24.Theorganizationalsohasacentralofficewherelocaldevelopmenttakesplace;thecentralofficeexistsonthe10.0.0.0/8subnet.APerforceserviceresidesinthe10.0.0.0/8subnet,andareplicaresidesinthe192.168.10.0/24subnet.Usersattheremotesitebelongtothegroupremotedev,andoccasionallyvisitthecentraloffice.EachsubnetalsohasacorrespondingsetofIPv6addresses.

Toensurethatmembersoftheremotedevgroupusethereplicawhileworkingattheremotesite,butdonotusethereplicawhenvisitingthelocalsite,addthefollowinglinestoyourprotectionstable:

list group remotedev 192.168.10.0/24 -//...

list group remotedev [2001:db8:16:81::]/48 -//...

write group remotedev proxy-192.168.10.0/24 //...

write group remotedev proxy-[2001:db8:16:81::]/48 //...

list group remotedev proxy-10.0.0.0/8 -//...

list group remotedev proxy-[2001:db8:1008::]/32 -//...

35

How replica types handle requests

write group remotedev 10.0.0.0/8 //...

write group remotedev proxy-[2001:db8:1008::]/32 //...

ThefirstlinedenieslistaccesstoallusersintheremotedevgroupiftheyattempttoaccessHelixServerwithoutusingthereplicafromtheirworkstationsinthe192.168.10.0/24subnet.ThesecondlinedeniesaccessinidenticalfashionwhenaccessisattemptedfromtheIPV6[2001:db8:16:81::]/48subnet.

Thethirdlinegrantswriteaccesstoallusersintheremotedevgroupiftheyareusingthereplicaandareworkingfromthe192.168.10.0/24subnet.Usersofworkstationsattheremotesitemustusethereplica.(Thereplicaitselfdoesnothavetobeinthissubnet,forexample,itcouldbeat192.168.20.0.)ThefourthlinegrantsaccessinidenticalfashionwhenaccessisattemptedfromtheIPV6[2001:db8:16:81::]/48subnet.

Similarly,thefifthandsixthlinesdenylistaccesstoremotedevuserswhentheyattempttousethereplicafromworkstationsonthecentralofficessubnets(10.0.0.0/8and[2001:db8:1008::]/32).TheseventhandeighthlinesgrantwriteaccesstoremotedevuserswhoaccesstheHelixServerdirectlyfromworkstationsonthecentralofficessubnets.Whenvisitingthelocalsite,usersfromtheremotedevgroupmustaccesstheHelixServerdirectly.

WhenthePerforceserviceevaluatesprotectionstableentries,thedm.proxy.protectsconfigurableisalsoevaluated.

dm.proxy.protectsdefaultsto1,whichcausestheproxy-prefixtobeprependedtoallclienthostaddressesthatconnectviaanintermediary(proxy,broker,replica,oredgeserver),indicatingthattheconnectionisnotdirect.

Settingdm.proxy.protectsto0removestheproxy-prefixandallowsyoutowriteasinglesetofprotectionentriesthatapplybothtodirectly-connectedclientsaswellastothosethatconnectviaanintermediary.Thisismoreconvenientbutlesssecureifitmattersthataconnectionismadeusinganintermediary.Ifyouusethissetting,allintermediariesmustbeatrelease2012.1orhigher.

How replica types handle requestsOnewayofexplainingthedifferencesbetweenreplicatypesistodescribehoweachtypehandlesuserrequests;whethertheserverprocessesthemlocally,whetheritforwardsthem,orwhetheritreturnsanerror.Thefollowingtabledescribesthesedifferences.

n Read onlycommandsincludep4 files,p4 filelog,p4 fstat,p4 user -o

n Work-in-progresscommandsincludep4 sync,p4 edit,p4 add,p4 delete,p4 integrate,p4 resolve,p4 revert,p4 diff,p4 shelve,p4 unshelve,p4 submit,p4 reconcile.

n Global updatecommandsincludep4 user,p4 group,p4 branch,p4 label,p4 depot,p4 stream,p4 protect,p4 triggers,p4 typemap,p4 server,p4 configure,p4 counter.

36

Configuring a read-only replica

Replica type Read-only commands

p4 sync, p4 client

Work-in-progress commands

Global update commands

Depotstandby,standby,replica

Yes,local Error Error Error

Forwardingstandby,forwardingreplica

Yes,local Forward Forward Forward

Buildserver Yes,local Yes,local Error Error

Edgeserver Yes,local Yes,local Yes,local Forward

Standardserver,depotmaster,commitserver

Yes,local Yes,local Yes,local Yes,local

Configuring a read-only replicaTosupportwarmstandbyservers,areplicaserverrequiresanup-to-datecopyofboththemasterserversmetadataanditsversionedfiles.

Tip Tohelpthestandbyserverstayascurrentaspossiblewiththemasterserver,considersettingtherpl.journalcopy.locationconfigurable.Thevalueof1couldkeepthestandbyserver'sjournalcopymorecurrentwiththemasterserver'sjournalbywritingthejournalcopytoafasterdevicethanthedeviceinthejournalPrefixconfigurabledefinedforthestandbyserver.

Note Replicationisasynchronous,andareplicatedserverisnotrecommendedasthesolemeansofbackupordisasterrecovery.We recommend that you maintain a separate set of database checkpoints and depot backups.Disasterrecoveryandfailoverstrategiesarecomplexandsite-specific.PerforceConsultantsareavailabletoassistorganizationsintheplanninganddeploymentofdisasterrecoveryandfailoverstrategies.Fordetails,see:https://www.perforce.com/support/consulting.

ThefollowingextendedexampleconfiguresareplicaasawarmstandbyserverforanexistingHelixVersioningEnginewithsomedatainit.Forthisexample,assumethat:

n YourmasterserverisnamedMasterandisrunningonahostcalledmaster,usingport11111,anditsserverrootdirectoryis/p4/master

n YourreplicaserverwillbenamedReplica1andwillbeconfiguredtorunonahostmachinenamedreplica,usingport22222,anditsrootdirectorywillbe/p4/replica.

n Theserviceusernameisservice.

37

https://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/configurables.configurables.html#rpl.journalcopy.locationhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/configurables.configurables.html#journalPrefixhttps://www.perforce.com/support/consulting

Master server setup

Note YoucannotdefineP4NAMEusingthep4 configurecommand,becauseaservermustknowitsownnametousevaluessetbyp4 configure.

YoucannotdefineP4ROOTusingthep4 configurecommand,toavoidtheriskofspecifyinganincorrectserverroot.

Master server setup 38Creating the replica 41Starting the replica 42Testing the replica 42Using the replica 44Upgrading replica servers 45

Master server setupTodefinethebehaviorofthereplica,youenterconfigurationinformationintothemasterserversdb.configfileusingthep4 configure setcommand.Configurethemasterserverfirst;itssettingswillbereplicatedtothereplicalater.

Toconfigurethemaster,logintoHelixServerasasuperuserandperformthefollowingsteps:

1. TosettheservernamedReplica1tousemaster:11111asthemasterservertopullmetadataandversionedfiles,issuethecommand:

$ p4 -p master:11111 configure set

Replica1#P4TARGET=master:11111

HelixServerdisplaysthefollowingresponse:

For server Replica1, configuration variable 'P4TARGET' set to

'master:11111'

Note Toavoidconfusionwhenworkingwithmultipleserversthatappearidenticalinmanyways,usethe-uoptiontospecifythesuperuseraccountand-ptoexplicitlyspecifythemasterHelixServershostandport.

Theseoptionshavebeenomittedfromthisexampleforsimplicity.Inaproductionenvironment,specifythehostandportonthecommandline.

2. SettheReplica1servertosavethereplicaserverslogfileusingaspecifiedfilename.Keepingthelognamesuniquepreventsproblemswhencollectingdatafordebuggingorperformancetrackingpurposes.

$ p4 configure set Replica1#P4LOG=replica1Log.txt

38

Master server setup

3. SettheReplica1serverconfigurableto1,whichisequivalenttospecifyingthe-vserver=1serverstartupoption:

$ p4 configure set Replica1#server=1

4. Toenableprocessmonitoring,setReplica1'smonitorconfigurableto1:

$ p4 configure set Replica1#monitor=1

5. TohandletheReplica1replicationprocess,configurethefollowingthreestartup.ncommands.(Whenpassingmultipleitemsseparatedbyspaces,youmustwraptheentiresetvalueindoublequotes.)

Thefirststartupprocesssetsp4 pulltopollonceeverysecondforjournaldataonly:

$ p4 configure set "Replica1#startup.1=pull -i 1"

Thenexttwosettingsconfiguretheservertospawntwop4 pullthreadsatstartup,eachofwhichpollsoncepersecondforarchivedatatransfers.

$ p4 configure set "Replica1#startup.2=pull -u -i 1"

$ p4 configure set "Replica1#startup.3=pull -u -i 1"

Eachp4 pull -ucommandcreatesaseparatethreadforreplicatingarchivedata.Heavily-loadedserversmightrequiremorethreads,ifarchivedatatransferbeginstolagbehindthereplicationofmetadata.Todetermineifyouneedmorep4 pull -uprocesses,readthecontentsoftherdb.lbrtable,whichrecordsthearchivedatatransferredfromthemasterHelixServertothereplica.

Todisplaythecontentsofthistablewhenareplicaisrunning,run:

$ p4 -p replica:22222 pull -l

Likewise,ifyouonlyneedtoknowhowmanyfiletransfersareactiveorpending,usep4 -p replica:22222 pull -l -s.

Ifp4 pull -l -sindicatesalargenumberofpendingtransfers,consideraddingmorep4 pull -u startup.ncommandstoaddresstheproblem.

Ifaspecificfiletransferisfailingrepeatedly(perhapsduetounrecoverableerrorsonthemaster),youcancancelthependingtransferwithp4 pull -d -f file -r rev,wherefileandrevrefertothefileandrevisionnumber.

39

Master server setup

6. Setthedb.replication(metadataaccess)andlbr.replication(depotfileaccess)configurablestoreadonly:

$ p4 configure set Replica1#db.replication=readonly

$ p4 configure set Replica1#lbr.replication=readonly

Becausethisreplicaserverisintendedasawarmstandby(failover)server,boththemasterserversmetadataanditslibraryofversioneddepotfilesarebeingreplicated.Whenthereplicaisrunning,usersofthereplicawillbeabletoruncommandsthataccessbothmetadataandtheserverslibraryofdepotfiles.

7. Createtheserviceuser:

$ p4 user -f service

Theuserspecificationfortheserviceuseropensinyourdefaulteditor.Addthefollowinglinetotheuserspecification:

Type: service

Savetheuserspecificationandexityourdefaulteditor.

Bydefault,theserviceuserisgrantedthesame12-hourlogintimeoutasstandardusers.Topreventtheserviceusersticketfromtimingout,createagroupwithalongtimeoutonthemasterserver.Inthisexample,theTimeout:fieldissettotwobillionseconds,approximately63years:

$ p4 group service_group

Users: service

Timeout: 2000000000

Formoredetails,see"Ticketsandtimeoutsforserviceusers"onpage32.

8. Settheserviceuserprotectionstosuperinyourprotectionstable.(See"Permissionsforserviceusers"onpage33.)ItisgoodpracticetosetthesecuritylevelofallyourHelixServerstoatleast1(preferablyto3,soastorequireastrongpasswordfortheserviceuser,andideallyto4,toensurethatonlyauthenticatedserviceusersmayattempttoperformreplicaorremotedepottransactions.)

$ p4 configure set security=4

$ p4 passwd

9. SettheReplica1configurablefortheserviceUsertoservice.

$ p4 configure set Replica1#serviceUser=service

Thisstepconfiguresthereplicaservertoauthenticateitselftothemasterserverastheserviceuser;thisisequivalenttostartingp4dwiththe-u serviceoption.

40

Creating the replica

10. Iftheuserrunningthereplicaserverdoesnothaveahomedirectory,orifthedirectorywherethedefault.p4ticketsfileistypicallystoredisnotwritablebythereplicasHelixServerprocess,setthereplicaP4TICKETSvaluetopointtoawritableticketfileinthereplicasHelixServerrootdirectory:

$ p4 configure set

"Replica1#P4TICKETS=/p4/replica/.p4tickets"

Creating the replicaToconfigureandstartareplicaserver,performthefollowingsteps:

1. Boot-strapthereplicaserverbycheckpointingthemasterserver,andrestoringthatcheckpointtothereplica:

$ p4 admin checkpoint

(Foranewsetup,wecanassumethecheckpointfileisnamedcheckpoint.1)

2. MovethecheckpointtothereplicaserversP4ROOTdirectoryandreplaythecheckpoint:

$ p4d -r /p4/replica -jr $P4ROOT/checkpoint.1

3. Copytheversionedfilesfromthemasterservertothereplica.

Versionedfilesincludebothtext(inRCSformat,endingwith,v)andbinaryfiles(directoriesofindividualbinaryfiles,eachdirectoryendingwith,d).Ensurethatyoucopythetextfilesinamannerthatcorrectlytranslateslineendingsforthereplicahostsfilesystem.

Ifyourdepotsarespecifiedusingabsolutepathsonthemaster,usethesamepathsonthereplica.(OruserelativepathsintheMap:fieldforeachdepot,sothatversionedfilesarestoredrelativetotheserversroot.)

4. Tocreateavalidticketfile,usep4 logintoconnecttothemasterserverandobtainaticketonbehalfofthereplicaserversserviceuser.Onthemachinethatwillhostthereplicaserver,run:

$ p4 -u service -p master:11111 login

ThenmovethetickettothelocationthatholdstheP4TICKETSfileforthereplicaserversserviceuser.

Atthispoint,yourreplicaserverisconfiguredtocontactthemasterserverandstartreplication.Specifically:

n Aserviceuser(service)inagroup(service_group)withalongtickettimeout

n Avalidticketforthereplicaserversserviceuser(fromp4 login)

41

Starting the replica

n Areplicatedcopyofthemasterserversdb.config,holdingthefollowingpreconfiguredsettingsapplicabletoanyserverwithaP4NAMEofReplica1,specifically:

l Aspecifiedserviceuser(namedservice),whichisequivalenttospecifying-u serviceonthecommandline

l Atargetserverofmaster:11111,whichisequivalenttospecifying-t master:11111onthecommandline

l Bothdb.replicationandlbr.replicationsettoreadonly,whichisequivalenttospecifying-M readonly-D readonlyonthecommandline

l Aseriesofp4 pullcommandsconfiguredtorunwhenthemasterserverstarts

Starting the replicaTonameyourserverReplica1,setP4NAMEorspecifythe-Inoptionandstartthereplicaasfollows:

$ p4d -r /p4/replica -In Replica1 -p replica:22222 -d

Whenthereplicastarts,allofthemasterserversconfigurationinformationisreadfromthereplicascopyofthedb.configtable(whichyoucopiedearlier).Thereplicathenspawnsthreep4 pullthreads:onetopollthemasterserverformetadata,andtwotopollthemasterserverforversionedfiles.

Note Thep4 infocommanddisplaysinformationaboutreplicasandservicefieldsforuntaggedoutputaswellastaggedoutput.

Testing the replica

Testing p4 pullToconfirmthatthep4 pullcommands(specifiedinReplica1'sstartup.nconfigurations)arerunning,issuethefollowingcommand:

$ p4 -u super -p replica:22222 monitor show -a

18835 R service00:04:46 pull -i 1

18836 R service00:04:46 pull -u -i 1

18837 R service00:04:46 pull -u -i 1

18926 R super 00:00:00 monitor show -a

Ifyouneedtostopreplicationforanyreason,usethep4 monitor terminatecommand:

$ p4 -u super -p replica:22222 monitor terminate 18837 process

'18837' marked for termination

42

Testing the replica

Torestartreplication,eitherrestarttheHelixServerprocess,ormanuallyrestartthereplicationcommand:

$ p4 -u super -p replica:22222 pull -u -i 1

Ifthep4 pulland/orp4 pull -uprocessesareterminated,read-onlycommandswillcontinuetoworkforreplicausersaslongasthereplicaserversp4disrunning.

Testing file replicationCreateanewfileunderyourworkspaceview:

$ echo "hello world" > myfile

Markthefileforadd:

$ p4 -p master:11111 add myfile

Andsubmitthefile:

$ p4 -p master:11111 submit -d "testing replication"

Waitafewsecondsforthepullcommandsonthereplicatorun,thencheckthereplicaforthereplicatedfile:

$ p4 -p replica:22222 print //depot/myfile

//depot/myfile#1 - add change 1 (text)

hello world

Ifafiletransferisinterruptedforanyreason,andaversionedfileisnotpresentwhenrequestedbyauser,thereplicaserversilentlyretrievesthefilefromthemaster.

Note Replicaserversin-M readonly -D readonlymodewillretrieveversionedfilesfrommasterserversevenifstartedwithoutap4 pull -ucommandtoreplicateversionedfilestothereplica.Suchserversactas"on-demand"replicas,asdoserversrunningin-M readonly -D ondemandmodeorwiththeirlbr.replicationconfigurablesettoondemand.

Administrators:beawarethatcreatinganon-demandreplicaofthissortcanstillaffectserverperformanceorresourceconsumption,forexample,ifauserentersacommandsuchasp4 print //...,whichreadseveryfileinthedepot.

Verifying the replicaWhenyoucopiedtheversionedfilesfromthemasterservertothereplicaserver,youreliedontheoperatingsystemtotransferthefiles.Todeterminewhetherdatawascorruptedintheprocess,runp4 verifyonthereplicaserver:

$ p4 verify //...

43

Using the replica

Anyerrorsthatarepresentonthereplicabutnotonthemasterindicatecorruptionofthedataintransitorwhilebeingwrittentodiskduringtheoriginalcopyoperation.(Runp4 verifyonaregularbasis,becauseafailoverserversstorageisjustasvulnerabletocorruptionasaproductionserver.)

Using the replicaYoucanperformallnormaloperationsagainstyourmasterserver(p4 -p master:11111 command).Toreducetheloadonthemasterserver,directreporting(read-only)commandstothereplica(p4 -p replica:22222 command).Becausethereplicaisrunningin-M readonly -D readonlymode,commandsthatreadbothmetadataanddepotfilecontentsareavailable,andreportingcommands(suchasp4 annotate,p4 changes,p4 filelog,p4 diff2,p4 jobs,andothers)worknormally.However,commandsthatupdatetheserversmetadataordepotfilesareblocked.

Commands that update metadataSomescenariosarerelativelystraightforward:consideracommandsuchasp4 sync.Aplainp4 syncfails,becausewheneveryousyncyourworkspace,theHelixVersioningEnginemustupdateitsmetadata(the"have"list,whichisstoredinthedb.havetable).Instead,usep4 sync -ptopopulateaworkspacewithoutupdatingthehavelist:

$ p4 -p replica:22222 sync -p //depot/project/...@1234

Thisoperationsucceedsbecauseitdoesnotupdatetheserversmetadata.

Somecommandsaffectmetadatainmoresubtleways.Forexample,manyHelixServercommandsupdatethelast-updatetimethatisassociatedwithaspecification(forexample,auserorclientspecification).Attemptingtousesuchcommandsonreplicaserversproduceserrorsunlessyouusethe-ooption.Forexample,p4 client(whichupdatestheUpdate:andAccess:fieldsoftheclientspecification)fails:

$ p4 -p replica:22222 client replica_client

Replica does not support this command.

However,p4 client -oworks:

$ p4 -p replica:22222 client -o replica_client

(client spec is output to STDOUT)

Ifacommandisblockedduetoanimplicitattempttowritetotheserversmetadata,considerworkaroundssuchasthosedescribedabove.(Somecommands,likep4 submit,alwaysfail,becausetheyattempttowritetothereplicaserversdepotfiles;thesecommandsareblockedbythe-D readonlyoption.)

44

Upgrading replica servers

Using the Helix Broker to redirect commandsYoucanusetheHelixBrokerwithareplicaservertoredirectread-onlycommandstoreplicaservers.Thisapproachenablesallyouruserstoconnecttothesameprotocol:host:portsetting(thebroker).Inthisconfiguration,thebrokerisconfiguredtotransparentlyredirectkeycommandstowhicheverHelixVersioningEngineisappropriatetothetaskathand.

Foranexampleofsuchaconfiguration,seetheKnowledgeBasearticle,"UsingP4Brokertoredirectread-onlycommands".

Seealsothechapteron"HelixBroker"onpage80.

Upgrading replica serversItisbestpracticetoupgradeanyserverinstancereplicatingfromamasterserverfirst.Ifreplicasarechainedtogether,startatthereplicathatisfurthestdownstreamfromthemaster,andworkupstreamtowardsthemasterserver.Keepdownstreamreplicasstoppeduntiltheserverimmediatelyupstreamisupgraded.

Note Therehasbeenasignificantchangeinrelease2013.3thataffectshowmetadataisstoredindb.*files;despitethischange,thedatabaseschemaandtheformatofthecheckpointandthejournalfilesbetween2013.2and2013.3,remainsunchanged.

Consequently,inthisonecase(ofupgradesbetween2013.2and2013.3),itissufficienttostopthereplicauntilthemasterisupgraded,butthereplica(andanyreplicasdownstreamofit)mustbeupgradedtoat least 2013.2beforea2013.3masterisrestarted.

Whenupgradingbetween2013.2(orlower)and2013.3(orhigher),itisrecommendedtowaitforallarchivetransferstoendbeforeshuttingdownthereplicaandcommencingtheupgrade.Youmustmanuallydeletetherdb.lbrfileinthereplicaserversrootbeforerestartingthereplica.

SeetheKnowledgeBasearticle,"UpgradingReplicaServers".

Configuring a forwarding replicaAforwardingreplicaoffersablendofthefunctionalityoftheHelixProxywiththeimprovedperformanceofareplica.

Ifyouareauditingserveractivity,eachofyourforwardingreplicaserversmusthaveitsownP4AUDITlogconfigured.

Configuring the master server 46Configuring the forwarding replica 46

45

http://answers.perforce.com/articles/KB/1253?startURL=%2Farticles%2FKB_Article%2FUsing-P4Broker-With-Replica-Servershttp://answers.perforce.com/articles/KB/1253?startURL=%2Farticles%2FKB_Article%2FUsing-P4Broker-With-Replica-Servershttp://answers.perforce.com/articles/KB/2515

Configuring the master server

Configuring the master serverThefollowingexampleassumesanenvironmentwitharegularservernamedmaster,andaforwardingreplicaservernamedfwd-replicaonahostnamedforward.

1. Startbyconfiguringaread-onlyreplicaforwarmstandby;see"Configuringaread-onlyreplica"onpage37fordetails.(InsteadofReplica1,usethenamefwd-replica.)

2. Onthemasterserver,configuretheforwardingreplicaasfollows:

$ p4 server fwd-1667

Thefollowingformisdisplayed:

ServerID: fwd-1667

Name: fwd-replica

Type: server

Services: forwarding-replica

Address: tcp:forward:1667

Description:

Forwarding replica pointing to master:1666

Configuring the forwarding replica1. Onthereplicamachine,assignthereplicaserveraserverID:

$ p4 serverid fwd-1667

WhenthereplicaserverwiththeserverID:offwd-1667(whichwaspreviouslyassignedtheName:offwd-replica)pullsitsconfigurationfromthemasterserver,itwillbehaveasaforwardingreplica.

2. Onthereplicamachine,restartthereplicaserver:

$ p4 admin restart

Configuring a build farm serverContinuousintegrationandothersimilardevelopmentprocessescanimposeasignificantworkloadonyourHelixServerinfrastructure.AutomatedbuildprocessesfrequentlyaccesstheHelixServertomonitorrecentchangesandretrieveupdatedsourcefiles;theirclientworkspacedefinitionsandassociatedhavelistsalsooccupystorageandmemoryontheserver.Withabuildfarmserver,youcanoffloadtheworkloadoftheautomatedbuildprocessestoaseparatemachine,andensurethatyourmainHelixServersresourcesareavailabletoyourusersfortheirnormalday-to-daytasks.

46

Configuring the master server

Note BuildfarmserverswereimplementedinHelixServerrelease2012.1.Withtheimplementationofedgeserversin2013.2,wenowrecommendthatyouuseanedgeserverinsteadofabuildfarmserver.Asdiscussedin"Commit-edge"onpage59,edgeserversofferallthefunctionalityofbuildfarmserversandyetoffloadmoreworkfromthemainserverandimproveperformance,withtheadditionalflexibilityofbeingabletorunwritecommandsaspartofthebuildprocess.

AHelixVersioningEngineintendedforuseasabuildfarmmust,bydefinition:

n Permitthecreationandconfigurationofclientworkspaces

n Permitthoseworkspacestobesynced

Oneissuewithimplementingabuildfarmratherthanaread-onlyreplicaisthatunderHelixServer,bothofthoseoperationsinvolvewritestometadata:inordertouseaclientworkspaceinabuildenvironment,theworkspacemustcontainsomeinformation(evenifnothingmorethantheclientworkspaceroot)specifictothebuildenvironment,andinorderforabuildtooltoefficientlysyncaclientworkspace,abuildservermustbeabletokeepsomerecordofwhichfileshavealreadybeensynced.

Toaddresstheseissues,buildfarmreplicashosttheirownlocalcopiesofcertainmetadata:inadditiontotheHelixServercommandssupportedinaread-onlyreplicaenvironment,buildfarmreplicassupportthep4 clientandp4 synccommandswhenappliedtoworkspacesthatareboundtothatreplica.

Ifyouareauditingserveractivity,eachofyourbuildfarmreplicaserversmusthaveitsownP4AUDITlogconfigured.

Configuring the master server 47Configuring the build farm replica 48Binding workspaces to the build farm replica 49

Configuring the master serverThefollowingexampleassumesanenvironmentwitharegularservernamedmaster,andabuildfarmreplicaservernamedbuildfarm1onahostnamedbuilder.

1. Startbyconfiguringaread-onlyreplicaforwarmstandby;see"Configuringaread-onlyreplica"onpage37fordetails.(Thatis,createaread-onlyreplicanamedbuildfarm1.)

2. Onthemasterserver,configurethemasterserverasfollows:

$ p4 server master-1666

Thefollowingformisdisplayed:

# A Perforce Server Specification.

#

# ServerID: The server identifier.

# Type: The server type: server/broker/proxy.

# Name: The P4NAME used by this server (optional).

47

Configuring the build farm replica

# Address: The P4PORT used by this server (optional).

# Description: A short description of the server (optional).

# Services: Services provided by this server, one of:

# standard: standard Perforce server

# replica: read-only replica server

# broker: p4broker process

# proxy: p4p caching proxy

# commit-server: central server in a distributed installation

# edge-server: node in a distributed installation

# forwarding-replica: replica which forwards update commands

# build-server: replica which supports build automation

# P4AUTH: server which provides central authentication

# P4CHANGE: server which provides central change numbers

#

# Use 'p4 help server' to see more about server ids and services.

ServerID: master-1666

Name: master-1666

Type: server

Services: standard

Address: tcp:master:1666

Description:

Master server - regular development work

1. Createthemasterserversserver.idfile.Onthemasterserver,runthefollowingcommand:

$ p4 -p master:1666 serverid master-1666

2. Restartthemasterserver.

Onstartup,themasterserverreadsitsserverIDofmaster-1666fromitsserver.idfile.IttakesontheP4NAMEofmasterandusestheconfigurablesthatapplytoaP4NAMEsettingofmaster.

Configuring the build farm replica1. Onthemasterserver,configurethebuildfarmreplicaserverasfollows:

$ p4 server builder-1667

48

Binding workspaces to the build farm replica

The following form is displayed:

ServerID: builder-1667

Name: builder-1667

Type: server

Services: build-server

Address: tcp:builder:1667

Description:

Build farm - bind workspaces to builder-1667

and use a port of tcp:builder:1667

2. Createthebuildfarmreplicaserversserver.idfile.Onthereplicaserver(notthemasterserver),runthefollowingcommand

$ p4 -p builder:1667 serverid builder-1667

3. Restartthereplicaserver.

Onstartup,thereplicabuildfarmserverreadsitsserverIDofbuilder-1667fromitsserver.idfile.

Becausetheserverregistryisautomaticallyreplicatedfromthemasterservertoallreplicaservers,therestartedbuildfarmservertakesontheP4NAMEofbuildfarm1andusestheconfigurablesthatapplytoaP4NAMEsettingofbuildfarm1.

Inthisexample,thebuildfarmserveralsoacknowledgesthebuild-serversettingintheServices:fieldofitsp4 serverform.

Binding workspaces to the build farm replicaAtthispoint,thereshouldbetwoserversinoperation:amasterservernamedmaster,withaserverIDofmaster-1666,andabuild-serverreplicanamedbuildfarm1,withaserverIDofbuilder-1667.

1. Bindclientworkspacestothebuildfarmserver.

Becausethisserverisconfiguredtoofferthebuild-serverservice,itmaintainsitsownlocalcopyofthelistofclientworkspaces(db.domainanddb.view.rp)andtheirrespectivehavelists(db.have.rp).

Onthereplicaserver,createaclientworkspacewithp4 client:

$ p4 -c build0001 -p builder:1667 client build0001

49

Configuring a replica with shared archives

Whencreatinganewworkspaceonthebuildfarmreplica,youmustensurethatyourcurrentclientworkspacehasaServerIDthatmatchesthatrequiredbybuilder:1667.Becauseworkspacebuild0001doesnotyetexist,youmustmanuallyspecifybuild0001asthecurrentclientworkspacewiththe-c clientnameoptionandsimultaneouslysupplybuild0001astheargumenttothep4 clientcommand.Formoreinformation,seetheKnowledgeBasearticleonBuildFarmClientManagement.

Whenthep4 clientformappears,settheServerID:fieldtobuilder-1667.

2. Synctheboundworkspace

Becausetheclientworkspacebuild0001isboundtobuilder-1667,usersonthemasterserverareunaffected,butusersonthebuildfarmserverarenotonlyabletoedititsspecification,theyareabletosyncit:

$ export P4PORT=builder:1667

$ export P4CLIENT=build0001

$ p4 sync

Thereplicashavelistisupdated,anddoesnotpropagatebacktothemaster.Usersofthemasterserverareunaffected.

Inareal-worldscenario,yourorganizationsbuildengineerswouldre-configureyoursitesbuildsystemtousethenewserverbyresettingtheirP4PORTtopointdirectlyatthebuildfarmserver.Eveninanenvironmentinwhichcontinuousintegrationandautomatedbuildtoolscreateaclientworkspace(andsyncit)foreverychangesubmittedtothemasterserver,performanceonthemasterwouldbeunaffected.

Inareal-worldscenario,performanceonthemasterwouldlikelyimproveforallusers,asthenumberofreadandwriteoperationsonthemasterserversdatabasewouldbesubstantiallyreduced.

Iftherearedatabasetablesthatyouknowyourbuildfarmreplicadoesnotrequire,considerusingthe-Fand-Tfilteroptionstop4 pull.AlsoconsiderspecifyingtheArchiveDataFilter:,RevisionDataFilter:andClientDataFilter:fieldsofthereplicasp4 serverform.

Ifyourautomationloadshouldexceedthecapacityofasinglemachine,youcanconfigureadditionalbuildfarmservers.Thereisnolimittothenumberofbuildfarmserversthatyoumayoperateinyourinstallation.

Configuring a replica with shared archivesNormally,areplicaserviceretrievesitsmetadataandfilearchivesontheuser-definedpullinterval,forexamplep4 pull -i 1.Whenthelbr.replicationconfigurableissettoondemandorshared(thetwoaresynonymous),metadataisretrievedonthepullintervalandarchivefilesareretrievedonlywhenrequestedbyaclient;newfilesarenotautomaticallytransferred,norarepurgedfilesremoved.

50

http://answers.perforce.com/articles/KB/2496

Configuring a replica with shared archives

Whenareplicaserverisconfiguredtodirectlysharethesamephysicalarchivefilesasthemasterserver,whetherthereplicaandmasterarerunningonthesamemachineorvianetworksharedstorage,thereplicasimplyaccessesthearchivesdirectlywithoutrequiringthemastertosendthearchivesfilestothereplica.ThiscanformpartofaHighAvailabilityconfiguration.

Warning Whenarchivefilesaredirectlysharedbetweenareplicaandmasterserver,thereplicamusthavelbr.replicationsettoondemandorshared,orarchivecorruptionmayoccur.

Toconfigureareplicatosharearchivefileswithamaster,performthefollowingsteps:

1. Ensurethattheclocksforthemasterandreplicaserversaresynchronized.

Nothingneedstobedoneifthemasterandreplicaserversarehostedonthesameoperatingsystem.

SynchronizingclocksisasystemadministrationtaskthattypicallyinvolvesusingaNetworkTimeProtocolclienttosynchronizeanoperatingsystemsclockwithatimeserverontheInternet,oratimeserveryoumaintainforyourownnetwork.

Seehttp://support.ntp.org/bin/view/Support/InstallingNTPfordetails.

2. Ifyouhavenotalreadydoneso,configurethereplicaserverasaforwardingreplica.

See"Configuringaread-onlyreplica"onpage37.

3. Setlbr.replication.

Forexample:p4 configure set REP13-1#lbr.replication=ondemand

4. Restartthereplica,specifyingthesharearchivelocationforthereplicasroot.

Oncethesestepshavebeencompleted,thefollowingconditionsareineffect:

n archivefilecontentisonlyretrievedwhenrequested,andthoserequestsaremadeagainstthesharedarchives.

n noentriesarewrittentotherdb.lbrlibrarianfileduringreplication.

n commandsthatwouldschedulethetransferoffilecontent,suchasp4 pull -uandp4 verify -tarerejected:

$ p4 pull -u

This command is not used with an ondemand replica server.

$ p4 verify -t //depot/...

This command is not used with an ondemand replica server.

51

http://support.ntp.org/bin/view/Support/InstallingNTP

Filtering metadata during replication

n ifstartupconfigurables,suchasstartup.N=pull -u,aredefined,thereplicaserverattemptstorunsuchcommands.Sincetheattempttoretrievearchivecontentisrejected,thereplicasserverlogwillcontainthecorrespondingerror:

Perforce server error:

2014/01/23 13:02:31 pid 6952 service-od@21131 background

'pull -u -i 10'

This command is not used with an ondemand replica server.

Filtering metadata during replicationAspartofanHA/DRsolution,youtypicallywanttoensurethatallthemetadataandalltheversionedfilesarereplicated.Inmostotherusecases,particularlybuildfarmsand/orforwardingreplicas,thisleadstoagreatdealofredundantdatabeingtransferred.

Itisoftenadvantageoustoconfigureyourreplicaserverstofilterin(orout)dataonclientworkspacesandfilerevisions.Forexample,developersworkingononeprojectataremotesitedonottypicallyneedtoknowthestateofeveryclientworkspaceatothersiteswhereotherprojectsarebeingdeveloped,andbuildfarmsdontrequireaccesstotheendlessstreamofchangestoofficedocumentsandspreadsheetsassociatedwithatypicallargeenterprise.

Thesimplestwaytofiltermetadataisbyusingthe-T tableexcludelistoptionwithp4 pullcommand.Ifyouknow,forexample,thatabuildfarmhasnoneedtorefertoanyofyourusers'havelistsorthestateoftheirclientworkspaces,youcanfilteroutdb.haveanddb.workingentirelywithp4 pull -T db.have,db.working.

Excludingentiredatabasetablesisacoarse-grainedmethodofmanagingtheamountofdatapassedbetweenservers,requiressomeknowledgeofwhichtablesaremostlikelytobereferredtoduringHelixServercommandoperations,andoffersnomeansofcontroloverwhichversionedfilesarereplicated.

Youcangainmuchmorefine-grainedcontroloverwhatdataisreplicatedbyusingtheClientDataFilter:,RevisionDataFilter:,andArchiveDataFilter:fieldsofthep4 serverform.Theseoptionsenableyoutoreplicate(orexcludefromreplication)thoseportionsofyourserversmetadataandversionedfilesthatareofinterestatthereplicasite.

E x a m p l e Filtering out client workspace data and filesIfworkspacesforusersineachofthreesitesarenamedwithsite[123]-ws-username,areplicaintendedtoactaspartialbackupforusersatsite1couldbeconfiguredasfollows:

ServerID: site1-1668

Name: site1-1668

Type: server

Services: replica

Address: tcp:site1bak:1668

Description:

52

Filtering metadata during replication

Replicate all client workspace data, except the states of

workspaces of users at sites 2 and 3.

Automatically replicate .c files in anticipation of user

requests. Do not replicate .mp4 video files, which tend

to be large and impose high bandwidth costs.

ClientDataFilter:

-//site2-ws-*

-//site3-ws-*

RevisionDataFilter:

ArchiveDataFilter:

//....c

-//....mp4

Whenyoustartthereplica,yourp4 pullmetadatathreadmightresemblethefollowing:

$ p4 configure set "site1-1668#startup.1=pull -i 30"

Inthisconfiguration,onlythoseportionsofdb.havethatareassociatedwithsite1arereplicated.Allmetadataconcerningworkspacesassociatedwithsite2andsite3isignored.

Allfile-relatedmetadataisreplicated.Allfilesinthedepotarereplicated,exceptforthoseendingin.mp4.Fil