Helix Versioning Engine Administrator Guide: Fundamentals - 2016.2
Transcript of Helix Versioning Engine Administrator Guide: Fundamentals - 2016.2
-
Helix Versioning Engine Administrator
Guide:Fundamentals2017.2
October 2017
-
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"onpage305.
https://www.perforce.com/
-
Contents
How to use this guide 13Feedback 13
Otherdocumentation 13
Syntaxconventions 13
Whats new in this guide for this release 15"Triggersforexternalfiletransfer"onpage1 15
Serverbackgroundtasks 15
Parallelthreads 15
Overview 16Basicarchitecture 16
Basicworkflow 17
Administrativeaccess 18
NamingHelixServerobjects 18
Installing and upgrading the server 20Installarchitecture 20
Planningtheinstallation 20
Network 21CPU 21Memory 21Diskspaceallocation 21Filesystem 22Protectionsandpasswords 23
GettingHelixServer 23
Linuxpackage-basedinstallation 24
Installation 24Post-installationconfiguration 27Updating 29
UNIXnon-packageinstallation 31
Downloadingthefilesandmakingthemexecutable 32CreatingaHelixServerrootdirectory 32TellingHelixServerapplicationswhichporttoconnectto 32Communicatingportinformation 33IPv6supportandmixednetworks 34
3
-
RunningtheHelixserver(p4d)asanunprivilegeduser 34RunningfrominetdonUNIX 35StartingthePerforceservice 36StoppingthePerforceservice 36RestartingarunningPerforceservice 36
Windowsinstallation 37
Windowsservicesandservers 37InstallingthePerforceserviceonanetworkdrive 38StartingandstoppingthePerforceservice 38MultiplePerforceservicesunderWindows 38Windowsconfigurationparameterprecedence 40StartingandstoppingtheHelixserver 41Supportforlongfilenames 41
Installedfiles 41
UpgradingthePerforceservice 42
UsingoldHelixServerapplicationsafteranupgrade 43HelixServerLicensingandupgrades 43UpgradingHelixServer 43UpgradingHelixServer-between2013.2and2013.3 44Verifyingfilesbysignature 45
Releaseandlicenseinformation 46
Configuring the server 47Enablingdistributedversioning 47
Definingfiletypeswithp4typemap 47
Implementingsite-wideexclusivelockingwithp4typemap 50
Definingdepots 50
Managingclientrequests 51
UsingP4PORTtocontrolaccesstotheserver 51Requiringminimumclientrevisions 51Rejectingclientconnectionrequests 52Disablingusermetricscollectionprompt 53
Casesensitivityandmulti-platformdevelopment 54
HelixserveronUNIX 54HelixserveronWindows 55
SettingupandmanagingUnicodeinstallations 55
Overview 55
4
-
SettingupaserverforUnicode 56ConfiguringclientsforUnicode 59TroubleshootinguserworkstationsinUnicodeinstallations 62
Configuringlogging 62
Loggingerrors 63Loggingfileaccess 63
ConfiguringP4Vsettings 63
ViewingeffectiveP4Vproperties 64PrecedenceofP4Vsettings 64Performance-relatedP4Vproperties 65Feature-relatedP4Vproperties 67MiscellaneousP4Vproperties 70Swarmintegrationproperties 71StagingP4Vhelpfileslocally 73TroubleshootingP4Vproperties 74
Windowsconfigurationparameterprecedence 75
Working with depots 77Overview 77
Namingdepots 77Listingdepots 78Deletingdepots 78Movingdepotsinaproductionenvironment 78
Standarddepots 78
Streamdepots 79
Specdepot 79
Creatingthespecdepot 80Populatingthespecdepotwithcurrentforms 80Controllingwhichspecsareversioned 81Largesitesandoldfilesystems 81
Archivedepots 82
Unloaddepot 82
Remotedepotsanddistributeddevelopment 82
Howremotedepotswork 83Usingremotedepotsforcodedrops 84
Securing the server 89Securingtheserver:workflow 89
5
-
UsingSSLtoencryptconnectionstoaHelixserver 90
Serverandclientsetup 90Keyandcertificatemanagement 90Keyandcertificategeneration 91Secondaryciphersuite 94UsingSSLinamixedenvironment 94
Usingfirewalls 94
Authenticationoptions 95
Overview 95Serversecuritylevels 95Definingauthenticationforusers 97
Authenticatingusingpasswordsandtickets 98
Password-basedauthentication 99Passwordstrengthrequirements 99Managingandresettinguserpasswords 100Ticket-basedauthentication 100Loginprocessfortheuser 101Loginprocessfortheserver 101LoggingoutofHelixServer 102Determiningticketstatus 102Invalidatingausersticket 103
LDAPauthentication 103
AuthenticatingagainstActiveDirectoryandLDAPservers 103CreatinganLDAPconfiguration 104DefiningLDAP-relatedconfigurables 107AuthorizationusingLDAPgroups 108TestingandenablingLDAPconfigurations 108GettinginformationaboutLDAPservers 109UsingLDAPwithsinglesign-ontriggers 110
Authorizingaccess 110
Whenshouldprotectionsbeset? 110Settingprotectionswithp4protect 110Grantingaccesstogroupsofusers 118Commentsinprotectiontables 122Howprotectionsareimplemented 122AccesslevelsrequiredbyHelixServercommands 123
Backup and recovery 132
6
-
Backupandrecoveryconcepts 132
Checkpointfiles 133Journalfiles 135Versionedfiles 137
Backupprocedures 138
Recoveryprocedures 141
Databasecorruption,versionedfilesunaffected 141Bothdatabaseandversionedfileslostordamaged 143Ensuringsystemintegrityafteranyrestoration 145
Monitoring the server 146Monitoringdiskspaceusage 146
Specifyingvaluesforfilesysconfigurables 146Determiningavailablediskspace 147
Monitoringprocesses 147
Enablingprocessmonitoring 147Enablingidleprocessesmonitoring 148Listingrunningprocesses 148
Settingservertraceandtrackingflags 149
Commandtracing 150Performancetracking 150
Showinginformationaboutlockedfiles 151
Auditinguserfileaccess 151
Loggingandstructuredlogfiles 152
Examplesofpossiblelogentries 152Loggingcommands 153Enablingstructuredlogging 153Structuredlogfilerotation 154
Managing the server and its resources 156Forcingoperationswiththe-fflag 156
Managingthesharingofcode 157
Managingdistributeddevelopment 158
DistributeddevelopmentusingFetchandPush 158Codedropswithoutconnectivity 160
Managingusers 161
Usertypes 161Preventingautomaticcreationofusers 163
7
-
Addingnewlicensedusers 164Renamingusers 164Deletingobsoleteusers 165Revertingfilesleftopenbyobsoleteusers 165
Deletingchangelistsandeditingchangelistdescriptions 165
Managingshelves 166
Backingupaworkspace 166
Managingdiskspace 167
DiskspaceRequirements 167Savingdiskspace 168Reclaimingdiskspacebyarchivingfiles 168Reclaimingdiskspacebyobliteratingfiles 170
Managingprocesses 171
Pausing,resuming,andterminatingprocesses 171Clearingentriesintheprocesstable 171
Managingthedatabasetables 171
ScriptedclientdeploymentonWindows 172
TroubleshootingWindowsinstallations 172
ResolvingWindows-relatedinstabilities 172ResolvingissueswithP4EDITORorP4DIFF 173
Tuning Helix Server for performance 174Tuningforperformance 174
Operatingsystems 174Disksubsystem 175Filesystems 175CPU 175Memory 177Network 177Journalandarchivelocation 178Usepatterns 178Usingread-onlyclientsinautomatedbuilds 178Usingparallelprocessingforsubmitsandsyncs 179
Improvingconcurrencywithlocklessreads 180
Commandsimplementinglocklessreads 181Overridingthedefaultlockingbehavior 183Observingtheeffectoflocklessreads 183
8
-
Side-trackserversmusthavethesamedb.peekinglevel 184Diagnosingslowresponsetimes 184
Hostnamevs.IPaddress 184Windowswildcards 185DNSlookupsandthehostsfile 185Locationofthep4executable 185Workingoverunreliablenetworks 185
Preventingserverswamp 186
Usingtightviews 187Assigningprotections 188Limitingdatabasequeries 188Limitingsimultaneousconnections 190Unloadinginfrequently-usedmetadata 190Scriptingefficiently 192Usingcompressionefficiently 194Otherserverconfigurables 195
Checkpointsfordatabasetreerebalancing 195
Customizing Helix Server: job specifications 196ThedefaultHelixServerjobtemplate 196
Thejobtemplatesfields 197
TheFields:field 198TheValues:fields 200ThePresets:field 200TheComments:field 201
Caveats,warnings,andrecommendations 202
Example:acustomtemplate 202
Workingwiththird-partydefecttrackingsystems 204
P4DTG,thePerforceDefectTrackingGateway 204Buildingyourownintegration 205
Using triggers to customize behavior 206Creatingtriggers 206
Sampletrigger 207Triggerdefinition 208Executionenvironment 210Triggerbasics 212
Triggeringonsubmits 219
9
-
Change-submittriggers 221Change-contenttriggers 222Change-committriggers 224
Triggeringonpushesandfetches 225
Similaritybetweenp4submitandp4push 225Differencesbetweenp4submitandp4push 226Fieldsonap4pushtrigger 227Push-submittriggers 228Push-contenttriggers 229Push-committriggers 231
Triggeringbeforeoraftercommands 232
Parsingtheinputdictionary 233Additionaltriggersforpushandfetchcommands 234
Triggeringonjournalrotation 235
Triggeringonshelvingevents 236
Shelve-submittriggers 237Shelve-committriggers 238Shelve-deletetriggers 238
Triggeringonfixes 239
Fix-addandfix-deletetriggers 240Triggeringonforms 241
Form-savetriggers 242Form-outtriggers 243Form-intriggers 244Form-deletetriggers 246Form-committriggers 246
Triggeringtouseexternalauthentication 247
Auth-checkandservice-checktriggers 250Singlesignonandauth-check-ssotriggers 251Triggeringforexternalauthentication 254
Triggeringtoaffectarchiving 255
Triggeringwithdepotsoftypegraph 257
graph-push-completetrigger 257Triggersforexternalfiletransfer 258
Replicaarchivepullthreads 258Edgeserversubmits 259
10
-
Triggerscriptvariables 260
Helix Versioning Engine (p4d) Reference 268Syntax 268
Description 268
ExitStatus 268
Options 268
UsageNotes 274
RelatedCommands 275
Moving a Helix Versioning Engine to a new machine 276Movingbetweenmachinesofthesamebyteorder 276
Movingbetweendifferentbyteordersthatusethesametextformat 277
MovingbetweenWindowsandUNIX 278
ChangingtheIPaddressofyourserver 278
Changingthehostnameofyourserver 278
Helix Versioning Engine Control (p4dctl) 279Installation 279
Configurationfileformat 279
Environmentblock 280Serverblock 281Servicetypesandrequiredsettings 283Configurationfileexamples 284Usingmultipleconfigurationfiles 285
p4dctlcommands 286
Glossary 288License Statements 305
11
-
How to use this guideThisguidedescribestheinstallation,configuration,andmanagementofHelixServerwithitsunderlyingHelixVersioningEngine(alsoreferredtoasHelixserverorp4d),includingtaskstypicallyperformedbya:
n systemadministrator,suchasinstallingandconfiguringthesoftwareandensuringuptimeanddataintegrity
n HelixServeradministrator,suchassettingupHelixServerusers,configuringHelixServerdepotaccesscontrols,andresettingHelixServeruserpasswords
AHelixServeradministratordoesnotrequireroot-levelaccess,soaHelixServeradministratorisnotnecessarilyasystemadministrator.
UsethisGuidewiththeP4 Command Reference.
Fordistributedservers,proxies,andbrokers,seeHelix Versioning Engine Administrator Guide: Multi-Site Deployment
Other documentationSeehttps://www.perforce.com/support/self-service-resources/documentation.
Syntax conventionsHelixdocumentationusesthefollowingsyntaxconventionstodescribecommandlinesyntax.
Notation Meaningliteral Mustbeusedinthecommandexactlyasshown.
italics Aparameterforwhichyoumustsupplyspecificinformation.Forexample,foraserveridparameter,supplytheIDoftheserver.
[-f] Theenclosedelementsareoptional.Omitthebracketswhenyoucomposethecommand.
13
http://www.perforce.com/perforce/doc.current/manuals/cmdref/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4dist/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4dist/index.htmlmailto:[email protected]://www.perforce.com/support/self-service-resources/documentation
-
Syntax conventions
Notation Meaning
... 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.
14
-
Whats new in this guide for this release
Whats new in this guide for this releaseThissectionprovidesasummarywithlinkstotopicsinthisreference.Foracompletelist,seetheRelease Notes.
"Triggers for external file transfer" on page258See"Triggersforexternalfiletransfer"onpage258
Server background tasksSeep4bgtaskintheCommandReference
Parallel threads p4shelvenowacceptsthe--parallelflagtospecifythatmultiplefilesshouldbetransferredinparallel,usingindependentnetworkconnectionsfromautomatically-invokedchildprocesses.Inaddition,newconfigurablesnet.parallel.shelve.*allowp4shelvetoautomaticallyuseparallelthreadstotransferfiles.Pleaseseep4 help shelveandp4 help configurablesforcompleteinformation.
Thenet.parallel.sync.svrthreadsconfigurablereducesthenumberofparalleltransmitthreadsusedbysynccommandswhenthetotalnumberof"user-transmit"threads(fromallcommands)runningconcurrentlyintheserverwouldexceedthevalueofthisconfigurable.Servermonitoringmustbeenabledforthisnewconfigurabletotakeeffect.
15
http://www.perforce.com/perforce/doc.current/user/relnotes.txthttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_bgtask.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/p4_shelve.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/configurables.configurables.html#net.parallel.sync.svrthreads
-
OverviewReadSolutions Overview: Helix Version Control Systembeforeyoureadthisguide.
Basic architectureThesimplestHelixServerconfigurationconsistsofaclientapplicationandserverapplicationcommunicatingoveraTCP/IPconnection.Theserverapplicationmanagesasinglerepositorythatconsistsofoneormoredepots.Aclientapplicationcommunicateswiththeservertoallowtheusertoview:
n treesofversionedfiles
n repositorymetadata(filehistory,users,groups,labels,permissions)
Clientsalsomanagelocalworkspaces(localdirectories)thatcontainasubsetofthefilesintherepository.Userscanview,checkout,andmodifytheselocalfilesandsubmitchangesbacktotherepository.Versionedfilesarestoredontheserverindepotsofvarioustypes,suchas:
n local
n stream
n graph,whichsupportsGitrepos
Figure 4-1 Single server
16
http://www.perforce.com/perforce/doc.current/manuals/overview/index.html
-
Basic workflow
Administratorssupportthisarchitecturebyinstallingandconfiguringtheserver,settingupusersandsecurity,monitoringperformance,managingtheresourcesusedbytheserver,andcustomizingthebehavioroftheserver.
Tip Variousoptionsforfederatedservices,suchasproxy,broker,andreplica,areexplainedintheMulti-SiteDeploymentguide.
Seealso"Centralizedanddistributedarchitecture"inUsingHelixCoreforDistributedVersioning(DVCS).
Basic workflowThisbookisroughlyorganizedaccordingtotheadministratorworkflow.Thissectionsummarizesthebasicworkflowforsettingup,configuring,andmanagingHelixServer.
1. SetuptheenvironmentinwhichyouwillinstallHelixServer.
Reviewinstallationpre-requisitesin"Planningtheinstallation"onpage20.
2. DownloadandinstallHelixServer.
See"Installingandupgradingtheserver"onpage20.
3. Starttheserver.
Seetheappropriatesectiononstartingtheserverin"Installingandupgradingtheserver"onpage20.
4. Executethep4 protectcommandtorestrictaccesstotheserver.
See"Whenshouldprotectionsbeset?"onpage110.
5. Configuretheserver.
Basicconfigurationincludesenablingdistributedversioningifneeded,definingdepots,definingcasesensitivityandunicode,managingclientrequests,configuringlogging,andconfiguringP4Vsettings.See"Configuringtheserver"onpage47.
6. Defineadditionaldepotsifneeded.
See"Workingwithdepots"onpage77.
7. Addusersiftheyarenotautomaticallyaddedonlogin.
See"Creatingstandardusers"onpage161.
8. Securetheserver:setupsecureclient-serverconnection.Setupauthorizationandauthentication.
See"Securingtheserver"onpage89.
9. Backuptheserver.
See"Securingtheserver"onpage89.
17
https://www.perforce.com/perforce/doc.current/manuals/p4dist/#P4Dist/chapter.concepts.htmlhttps://www.perforce.com/perforce/doc.current/manuals/p4dist/https://www.perforce.com/perforce/doc.current/manuals/p4dist/https://www.perforce.com/perforce/doc.current/manuals/dvcs/#DVCS/intro.central-and-distributed.htmlhttps://www.perforce.com/perforce/doc.current/manuals/dvcs/
-
Administrative access
10. Monitorserverperformanceandresourceuse.
See"Monitoringtheserver"onpage146.
11. Managetheserveranditsresources:changelists,users,codesharing,diskspace,andprocesses.
See"Managingtheserveranditsresources"onpage156.
12. Tunetheservertoimproveperformance.
See"TuningHelixServerforperformance"onpage174.
13. CustomizeHelixServerbyextendingjobdefinitions.
See"CustomizingHelixServer:jobspecifications"onpage196.
14. CustomizeHelixServerusingtriggerscripts.
See"Usingtriggerstocustomizebehavior"onpage206.
Administrative accessHelixServersecuritydependsonthesecuritylevelthatissetandonhowauthenticationandaccessprivilegesareconfigured;thesearedescribedin"Securingtheserver"onpage89.Accesslevelsrelevantfortheadministratorareadminandsuper:
n admingrantspermissiontorunHelixServercommandsthataffectmetadata,butnotserveroperation.Auserwithadminaccesscanedit,delete,oraddfiles,andcanusethep4 obliteratecommand.
n supergrantspermissiontorunallHelixServercommands,allowsthecreationofdepotsandtriggers,permitsthedefinitionofprotections,andenablesusermanagement.
Usersoftypeoperatorareallowedtoruncommandsthataffectserveroperation,butnotmetadata.
AllservercommandsdocumentedintheP4 Command Referenceindicatetheaccesslevelneededtoexecutethatcommand.
UntilyoudefineaHelixServersuperuser,everyuserisasuperuserandcanrunanyHelixServercommandonanyfile.AfteryoustartanewPerforceservice,usethefollowingcommand:
$ p4 protect
assoonaspossibletodefineaHelixServersuperuser.
Naming Helix Server objectsAsyouworkwithHelixServer,youwillbecreatingavarietyofobjects:clients,depots,branches,jobs,labels,andsoon.Thissectionprovidessomeguidelinesyoucanusewhennamingtheseobjects.
18
http://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html
-
Naming Helix Server objects
Object NameBranches Agoodideatonamethem,perhapsusingaconventiontoindicatetherelationshipofthe
branchtootherbranchesortoyourworkflow.
Client Dependsonusage,butsomecommonnamingconventionsinclude:
n user.machineTag.product
n user.machineTag.product.branch
Whetheryouuseproductorproduct.branchdependsonwhetheryourworkspacegetsre-purposedfromstreamtostream(inwhichcaseyouusejustproduct),orwhetheryouhavemultipleworkspaces,oneforeachbranch(inwhichcaseyouuseproduct.branch,effectivelytyingtheworkspacenametothebranch).
Aclientmaynothavethesamenameasadepot.
Depot Depotnamesarepartofanorganizationshierarchyforallyourdigitalassets.Takecareinchoosingnamesandinplanningthedirectorystructure.
Itisbesttokeepthenamesshort.
Aclientmaynothavethesamenameasadepot.
Jobs Usenamesthatmatchwhateveryourexternaldefecttrackerissueslooklike.ForexamplePRJ-1234forJIRAissues.
Labels Site-dependent,varieswithyourcodemanagementandversioningneeds.Forexample:R-3.2.0.
MachineTags
Thehostname,orsomethingsimpleanddescriptive.ForexampleWin7VM,P4MBPro(forHelixServerMacBookPro).
User TheOSuser.
19
-
Installing and upgrading the serverThischapterdescribeshowtoinstallthePerforceserviceorupgradeanexistinginstallation.Itcontainsinformationaboutthefollowingtopics:
n Pre-requisitesforinstallation
n Wheretoobtaininstallationfiles
n InstallingonUNIX(orMacOSX)
n InstallingonWindows
n Defaultlocationofinstalledfiles
n Upgradingyourinstallation
n Licenserequirements
ManyoftheexamplesinthisbookarebasedontheUNIXversionofthePerforceservice.Inmostcases,theexamplesapplyequallytobothWindowsandUNIXinstallations.ThematerialforUNIXalsoappliestoMacOSX.
Warning IfyouareupgradinganexistinginstallationtoRelease2013.3orlater,seethenotesin"UpgradingthePerforceservice"onpage42beforeproceeding.
Install architectureThechapter"Overview"onpage16describesthetwodeploymentoptionsthatarecoveredinthisbook.Thischapterfocusesontheinstallationoftheserverforconnectedclients.Seethe"Install"chapterofUsing Helix Server for Distributed Versioningforinformationonhowtoinstallaserverthatsupportsclientswhowanttoworkdisconnected.
Planning the installationThefollowingsectionsdescribesomeoftheissuesyouneedtothinkaboutbeforeinstallingandconfiguringtheserver.
20
http://www.perforce.com/perforce/doc.current/manuals/dvcs/index.html
-
Network
NetworkHelixServercanrunoveranyTCP/IPnetwork.Forremoteusersordistributedconfigurations,HelixServeroffersoptionslikeproxiesandthecommit/edgearchitecturethatcanenhanceperformanceoveraWAN.Compressioninthenetworklayercanalsohelp.Foradditionalinformationaboutnetworkandperformancetuning,see"TuningHelixServerforperformance"onpage174.
CPUCPUresourceconsumptioncanbeadverselyaffectedbycompression,locklessreads,orabadlydesignedprotectionstable.Ingeneral,thereisatrade-offbetweenspeedandthenumberofcores.Aminimumof2.4GHZand8coresisrecommended.Withgreaterspeed,fewercoreswilldo:forexample,a3.2GHZand4-coreprocessorwillalsowork.
Foradditionaldetails,see"CPU"onpage175.
MemoryThereareacoupleofguidelinesyoucanfollowtoanticipatememoryneeds:
n Multiplythenumberoflicensedusersby64MB.
n Allocate1.5kilobytesofRAMperfileinthedepot.
Ingeneral,HelixServerperformswellonmachinesthathavelargememoryfootprintsthatcanbeusedforfilesystemcache.I/Otoeventhefastestdiskwillbeslowerthanreadingfromthefilecache.Theseguidelinesonlyapplyforasingleserver.
Foradditionalinformationaboutmemoryandperformancetuning,see"TuningHelixServerforperformance"onpage174.
Disk space allocationPerforcediskspaceusageisafunctionofthreevariables:
n Numberandsizeofclientworkspaces
n Sizeofserverdatabase
n Sizeofserversarchiveofallversionedfiles
AllthreevariablesdependonthenatureofyourdataandhowheavilyyouusePerforce.
Theclientfilespacerequiredisthesizeofthefilesthatyouruserswillneedintheirclientworkspacesatanyonetime.
Theserversdatabasesizecanbecalculatedwithafairlevelofaccuracy;asaroughestimate,itrequires0.5kilobytesperuserperfile.(Forinstance,asystemwith10,000filesand50usersrequires250MBofdiskspaceforthedatabase).Thedatabasecanbeexpectedtogrowovertimeashistoriesoftheindividualfilesgrow.
21
-
Filesystem
Thesizeoftheserversarchiveofversionedfilesdependsonthesizesoftheoriginalfilesstoredandgrowsasrevisionsareadded.AgoodguidelineistoallocatesufficientspaceinyourP4ROOTdirectorytoholdthreetimesthesizeofyourusers'presentcollectionofversionedfiles,plusanadditional0.5KBperuserperfiletoholdthedatabasefilesthatstorethelistofdepotfiles,filestatus,andfilerevisionhistories.
Thedb.havefileholdsthelistoffilesopenedinclientworkspaces.Thisfiletendstogrowmorerapidlythanotherfilesinthedatabase.Ifyouareexperiencingissuesrelatedtothesizeofyourdb.havefileandareunabletoquicklyswitchtoaserverwithadequatesupportforlargefiles,deletingunusedclientworkspacespecificationsandreducingthescopeofclientworkspaceviewscanhelpalleviatetheproblem.
FilesystemFilesizeanddiskI/Oarethekeyissueshere.Formoreinformation,see"Filesystems"onpage175.
Filesystem performanceHelixServerisjudiciouswithregardstoitsuseofdiskI/O;itsmetadataiswell-keyed,andaccessesaremostlysequentialscansoflimitedsubsetsofthedata.Themostdisk-intensiveactivityisfilecheck-in,wheretheHelixVersioningEnginemustwriteandrenamefilesinthearchive.Serverperformancedependsheavilyontheoperatingsystemsfilesystemimplementation,andinparticular,onwhetherdirectoryupdatesaresynchronous.ServerperformanceisalsohighlydependentuponthecapabilitiesoftheunderlyinghardwaresI/Osubsystem.
AlthoughHelixServerdoesnotrecommendanyspecifichardwareconfigurationorfilesystem,Linuxserversaregenerallyfastest(owingtoLinuxsasynchronousdirectoryupdating),buttheymayhavepoorrecoveryifpoweriscutatthewrongtime.
PerformanceinsystemswheredatabaseandversionedfilesarestoredonNFS-mountedvolumesistypicallydependentontheimplementationofNFSinquestionortheunderlyingstoragehardware.HelixServerhasbeentestedandissupportedusingimplementationsthatsupporttheflockprotocol.
UnderLinuxandFreeBSD,databaseupdatesoverNFScanbeanissuebecausefilelockingisrelativelyslow;ifthejournalisNFS-mountedontheseplatforms,alloperationswillbeslower.Ingeneral(butinparticularonLinuxandFreeBSD),werecommendthattheHelixServerdatabase,depot,andjournalfilesbestoredondiskslocaltothemachinerunningtheHelixVersioningEngineprocessorthattheybestoredonalow-latencySANdevice.
TheseissuesaffectonlytheHelixVersioningEngineprocess(p4d).HelixServerapplications,(suchasp4,theHelixServerCommand-LineClient)havealwaysbeenabletoworkwithclientworkspacesonNFS-mounteddrives(forinstance,workspacesinusers'homedirectories).
Separate physical drives for server root and journalWhetherinstallingonUNIXorWindows,itisadvisabletohaveyourP4ROOTdirectory(thatis,thedirectorycontainingyourdatabaseandversionedfiles)onadifferentphysicaldrivethanyourjournalfile.
22
-
Protections and passwords
Bystoringthejournalonaseparatedrive,youcanbereasonablycertainthat,ifadiskfailurecorruptsthedrivecontainingP4ROOT,suchafailurewillnotaffectyourjournalfile.Youcanthenusethejournalfiletorestoreanylostordamagedmetadata.Separatingthelivejournalfromthedb.*filescanalsoimproveperformance.
Furtherdetailsareavailablein"Backupandrecovery"onpage132andin"Journalandarchivelocation"onpage178.
Protections and passwordsUntilyoudefineaHelixServersuperuser,everyuserisasuperuserandcanrunanyHelixServercommandonanyfile.AfteryoustartanewPerforceservice,use:
$ p4 protect
assoonaspossibletodefineaHelixServersuperuser.Tolearnmoreabouthowp4 protectworks,see"Authorizingaccess"onpage110.
Withoutpasswords,anyuserisabletoimpersonateanyotherHelixServeruser,eitherwiththe-uflagorbysettingP4USERtoanexistingHelixServerusername.UseofHelixServerpasswordspreventssuchimpersonation.SeetheHelix Versioning Engine User Guidefordetails.
Toset(orreset)auserspassword,eitherusep4 passwd username(asaHelixServersuperuser),andenterthenewpasswordfortheuser,orinvokep4 user -f username(alsowhileasaPerforcesuperuser)andenterthenewpasswordintotheuserspecificationform.
Thesecurity-consciousHelixServersuperuseralsousesp4 protecttoensurethatnoaccesshigherthanlistisgrantedtounprivilegedusers,p4 configuretosetthesecurityleveltoalevelthatrequiresthatallusershavestrongpasswords,andp4 grouptoassignalluserstogroups(and,optionally,torequireregularchangesofpasswordsforusersonaper-groupbasis,tosetaminimumrequiredpasswordlengthforallusersonthesite,andtolockoutusersforpredefinedamountsoftimeafterrepeatedfailedloginattempts).
Note AnalternatewaytoreducesecurityriskduringinitialsetuporduringamaintenanceintervalistostarttheHelixVersioningEngineusinglocalhost:portsyntax.Forexample:
$ p4d localhost:2019
Thisforcestheservertoignorenon-localconnectionrequests.
Forcompleteinformationaboutsecurity,see"Securingtheserver"onpage89.
Getting Helix ServerHelixServerrequiresatleasttwoexecutables:theHelixVersioningEngine,alsoreferredtoasthePerforceservice(p4donUnix,p4s.exeonWindows),andatleastoneHelixServerapplication(suchasp4onUNIXorp4.exeonWindows,alsoreferredtoastheCommand-LineClient).
ThePerforceserviceandapplicationsareavailablefromtheDownloadspageonthePerforcewebsite:
23
http://www.perforce.com/perforce/doc.current/manuals/p4guide/index.html
-
Linux package-based installation
http://www.perforce.com/downloads
Gotothewebpage,selectthefilesforyourplatform,andsavethefilestodisk.Inadditiontoplainbinaries,installersforWindowsarealsoavailableattheabovesite.Youareencouragedtousethem.
ManycomponentsarealsoavailableasLinuxpackages.SeeinstructionsinthenextsectionforinstallingOS-specificpackagesforselectLinuxdistributions.
Linux package-based installationThePerforceserviceisavailableintwodistributionpackageformats:Debian(.deb)forUbuntusystems,andRPM(.rpm)forCentOSandRedHatEnterpriseLinux(RHEL).
Usingdistributionpackagesgreatlysimplifiestheinstallation,update,andremovalofsoftware,asthetoolsthatmanagethesepackagesareawareofthedependenciesforeachpackage.
YoucaninstallpackagesforthePerforceserviceonthefollowingLinux(Intelx86_64)platforms:
n Ubuntu12.04LTS
n Ubuntu14.04LTS
n Ubuntu16.04LTS
n CentOSorRedHat6.x
n CentOSorRedHat7.x
Duringthecourseoftheinstallation,youwillbeaskedtomakechoicesaboutcasesensitivityandUnicodesettings.Pleasereadthefollowingsectionsnowtounderstandtheconsequencesofyourselections:
n "Casesensitivityandmulti-platformdevelopment"onpage54
n "SettingupandmanagingUnicodeinstallations"onpage55
Makesure,beforeyoustarttheinstall,thatyouhaverootlevelaccesstotheserverthatwillhostyourPerforceservice.
Installation1. Configure the Helix Server package repository.
Asroot,runoneofthefollowing:
a. For Ubuntu 12.04:
Createthefile/etc/apt/sources.list.d/perforce.listwiththefollowingcontent:
deb http://package.perforce.com/apt/ubuntu/ precise release
24
https://www.perforce.com/downloads
-
Installation
b. For Ubuntu 14.04:
Createthefile/etc/apt/sources.list.d/perforce.listwiththefollowingcontent:
deb http://package.perforce.com/apt/ubuntu/ trusty release
c. For Ubuntu 16.04:
Createthefile/etc/apt/sources.list.d/perforce.listwiththefollowingcontent:
deb http://package.perforce.com/apt/ubuntu/ xenial release
d. For CentOS/RHEL 6:
Createthefile/etc/yum.repos.d/perforce.repo,withthefollowingcontent:
[perforce]
name=Perforce
baseurl=http://package.perforce.com/yum/rhel/6/x86_64/
enabled=1
gpgcheck=1
e. For CentOS/RHEL 7:
Createthefile/etc/yum.repos.d/perforce.repo,withthefollowingcontent:
[perforce]
name=Perforce
baseurl=http://package.perforce.com/yum/rhel/7/x86_64/
enabled=1
gpgcheck=1
25
-
Installation
2. Import the Helix Server package signing key.
Runoneofthefollowing:
a. For Ubuntu:
$ wget -qO - https://package.perforce.com/perforce.pubkey
| sudo apt-key add -
b. For CentOS/RHEL (run this command as root):
# rpm --import
https://package.perforce.com/perforce.pubkey
Forinformationaboutverifyingtheauthenticityofthesigningkey,see:https://www.perforce.com/perforce-packages
3. Install the appropriate Perforce service package.
ThePerforceserviceisdividedintomultiplepackages,soyoucaninstalljustthecomponentsyouneed.Thecomponentpackagenamesare:
n helix-p4d
n helix-p4dctl
n helix-proxy
n helix-broker
n helix-cli
Thehelix-p4dpackageinstallsthemaincomponentofaPerforceservice,p4d,aswellasthecommandlineinterface,theservicecontroller,andaconfigurationscripttosetthemup.
Atminimum,youneedtoinstallthehelix-p4dpackage.Toinstalladifferentpackage,substituteitsnameforhelix-p4dinthecommandsbelow.
Runoneofthefollowing:
a. For Ubuntu:
$ sudo apt-get update
$ sudo apt-get install helix-p4d
b. For CentOS/RHEL (run this command as root):
# yum install helix-p4d
Thefilescontainedinthepackageareinstalled,andstatusinformationdescribingthemainelementsthathavebeeninstalledisdisplayed.
4. Run the post-installation configuration script.
Ifyouinstalledthehelix-p4dpackage,andifinstallationwassuccessful,proceedonto"Post-installationconfiguration"onthenextpage.
26
https://www.perforce.com/perforce-packages
-
Post-installation configuration
Post-installation configurationAfterthehelix-p4dpackagehasbeeninstalled,additionalconfigurationisrequired.Performthefollowingsteps:
1. Use the configure-helix-p4d.sh script to configure a Perforce service.
Note Theconfigure-helix-p4d.shscriptcanbeusedinafewdifferentways.Thestepsbelowoutlinethemoststraightforwardconfigurationusinginteractivemode,butyoucanreviewtheoptionsbyrunning:
$ sudo /opt/perforce/sbin/configure-helix-p4d.sh -h
Runininteractivemode:
$ sudo /opt/perforce/sbin/configure-helix-p4d.sh
Ininteractivemode,theconfigurationscriptbeginsbydisplayingasummaryofdefaultsettingsandthosewhichhaveoptionallybeensetwithacommandlineargument.
27
-
Post-installation configuration
2. Provide information to the configuration script.
Afterthesummary,theconfigurationscriptpromptsforinformationitneedstosetupyourPerforceservice.
Note IfyoualreadyhaveaPerforceserviceconfigured,andyousupplyitsservice name,thentheconfigurationscriptonlypromptsforsettingsthatyoucanchangeonanexistingservice.
Ateachprompt,youcanaccepttheproposeddefaultvaluebypressingEnter,oryoucanspecifyyourownvalue.
Thelistbelowcontainsdetailsabouttheoptionsforeachprompt:
a. The Service Name:
Thenameusedwhenmanagingthisservicewithp4dctl,forinstancewhenstartingandstoppingtheservice.
ThisnameisalsousedtosetthePerforceserveridattributeontheunderlyingp4dinstance,todistinguishitfromothersthatmaybeinyouroverallinstallation.
b. The Server Root (P4ROOT):
Thedirectorywhereversionedfilesandmetadatashouldbestored.
c. The Unicode Mode for the server:
Thisisoffbydefault.
Warning IfyouturnUnicodemodeon,youwillnotbeabletoturnitoff.BesureyouarefamiliarwithUnicodefunctionalitywhenselectingthismode.See"SettingupandmanagingUnicodeinstallations"onpage55forinformation.
d. The Case Sensitivity for the server:
Thisisonbydefault.
See"Casesensitivityandmulti-platformdevelopment"onpage54forinformation.
e. The Server Address (P4PORT):
ThisspecifiesthehostandportwherethePerforceserviceshouldlisten,andwhethertocommunicateinplaintextoroverSSL.Formoreinformation,see"Communicatingportinformation"onpage33.
f. Superuser login:
Thedesireduseridforanewusertobecreatedwithsuperlevelprivileges.
Formoreinformationaboutsuperusers,see"Accesslevels"onpage112.
28
-
Updating
g. Superuser password:
Thedesiredpasswordtobesetforthenewsuperuser.
Duetotheunlimitedprivilegesgrantedtothisuser,astrongpasswordisrequired.
Afteryouanswerallprompts,thescriptbeginsconfigurationaccordingtoyourchoices.Asitruns,thescriptdisplaysinformationabouttheconfigurationtakingplace.
Aftertheconfigurationhascompletedsuccessfully,asummaryisdisplayedwithdetailsaboutwhatwasdone,andwheresettingsarestored.
Youcannowconnecttotheservice,oryoucanmanagetheserviceusingthep4dctlutility.Formoreinformation,see"HelixVersioningEngineControl(p4dctl)"onpage279.
Updating
Important Thepackageupdatecommandswithapt-getoryumdonotcompletetheprocessofupdatingyourPerforceservice.PackagesforLinuxsimplifyonlycertainstepsofthatprocess.
UpdatingpackageswithoutcompletingtherestoftheupdateprocessleavesyourPerforceserviceinaprecariousstate.Makesuretoreadandunderstandtheentireprocessbeforeupdatinganypackages.
1. Review the general update process.
a. See"UpgradingthePerforceservice"onpage42fordetailsonthegeneral processforhowtoupdateaPerforceservice,onanyplatform.Youshouldreadandthoroughlyunderstandthissectionbeforecontinuing.
29
-
Updating
b. PackagesforLinuxhelpyouaccomplishonlyspecific stepsfromthegeneral process.IfyouareattemptingtoupdateyourPerforceserviceusingpackages,youshouldstillfollowthegeneral processlinkedabove,butwiththepackagespecificmodificationsbelow:
i. Youmaybeabletostop,checkpoint,andstartyourPerforceserviceusingp4dctl:
$ sudo -u perforce p4dctl [stop|checkpoint|start]
servicename
ii. Youdonotneedtomanuallyretrievethenewcomponentbinaries(suchasp4d)fromthePerforcewebsite;thepackageupdatecommandswithapt-getoryumaccomplishthisstep.
Platform-specificpackageupdatecommandsarebelow.
iii. YoustillneedtoupgradethePerforceservicedatabasetousethenewversionsofcomponentsdeliveredbythepackages.
Asaconvenience,2016.1andnewerpackagesattempttopresenttailoredinstructionsandcommandson-screenforupgradingthosePerforceservicedatabasesthatarediscoveredautomatically.
2. Determine if an updated package is available.
Note Toupdateadifferentpackage,substituteitsnameforhelix-p4dinthecommandsbelow.
Runoneofthefollowing:
a. For Ubuntu:
$ sudo apt-get update
$ sudo apt-cache madison helix-p4d
b. For CentOS/RHEL (run this command as root):
# yum --showduplicates list helix-p4d
30
-
UNIX non-package installation
3. Install an updated package.
Note Toupdateadifferentpackage,substituteitsnameforhelix-p4dinthecommandsbelow.
Thecommandtoupdateisthesameusedtoinstallinitially.
Runoneofthefollowing:
a. For Ubuntu:
$ sudo apt-get update
$ sudo apt-get install helix-p4d
b. For CentOS/RHEL (run this command as root):
# yum install helix-p4d
Important Failuretocompleteallupdatestepsinthegeneral processreferencedabovecouldresultincontinueddowntimeforyourPerforceservice.
UNIX non-package installationAlthoughyoucaninstallp4andp4dinanydirectory,onUNIX,theHelixServerapplicationstypicallyresidein/usr/local/bin,andthePerforceserviceisusuallylocatedeitherin/usr/local/binorinitsownserverrootdirectory.YoucaninstallHelixServerapplicationsonanymachinethathasTCP/IPaccesstothep4dhost.
TolimitaccesstothePerforceservicesfiles,ensurethatthep4dexecutableisownedandrunbyaHelixServeruseraccountthathasbeencreatedforthepurposeofrunningthePerforceservice.
ForanexampleUnixinstallationsee:
http://answers.perforce.com/articles/KB_Article/Example-Unix-Installation
Note Tomaximizeperformance,configuretheserverroot(P4ROOT)toresideonalocaldiskandnotanNFS-mountedvolume.Perforcesfile-lockingsemanticsworkwithNFSmountsonSolaris2.5.1andlater;someissuesstillremainregardingfilelockingonnoncommercialimplementationsofNFS(forinstance,LinuxandFreeBSD).Itisbesttoplacemetadataandjournaldataonseparatedrives
TheseissuesaffectonlytheHelixVersioningEngineprocess(p4d).HelixServerapplications(suchasp4,theHelixServerCommand-LineClient)havealwaysbeenabletoworkwithclientworkspacesonNFS-mounteddrives,suchasclientworkspaceslocatedinusers'homedirectories.
TostartusingHelixServer:
31
http://answers.perforce.com/articles/KB_Article/Example-Unix-Installation
-
Downloading the files and making them executable
1. Downloadthep4andp4dapplicationsforyourplatformfromthePerforcewebsite.
2. Makethedownloadedp4andp4dfilesexecutable.
3. CreateaserverrootdirectorytoholdtheHelixServerdatabaseandversionedfiles.
4. TellthePerforceservicewhatporttolistentobyspecifyingaTCP/IPporttop4d.
5. StartthePerforceservice(p4d).
6. Setthep4dportandaddressforHelixServerapplicationsbysettingtheP4PORTenvironmentvariable.
Downloading the files and making them executableOnUNIX(orMacOSX),youmustmakethep4andp4dbinariesexecutable.Afteryoudownloadthesoftware,usethechmodcommandtomakethemexecutable,asfollows:
$ chmod +x p4
$ chmod +x p4d
Creating a Helix Server root directoryThePerforceservicestoresalluser-submittedfilesandsystem-generatedmetadatainfilesandsubdirectoriesbeneathitsownrootdirectory.Thisdirectoryiscalledtheserver root.
Tospecifyaserverroot,eithersettheenvironmentvariableP4ROOTtopointtotheserverroot,orusethe-rserver_rootflagwheninvokingp4d.HelixServerapplicationsneverusetheP4ROOTdirectoryorenvironmentvariable;p4distheonlyprocessthatusestheP4ROOTvariable.
BecauseallHelixServerfilesarestoredbydefaultbeneaththeserverroot,thecontentsoftheserverrootcangrowovertime.See"Diskspaceallocation"onpage21forinformationaboutdiskspacerequirements.
ThePerforceservicerequiresnoprivilegedaccess;thereisnoneedtorunp4dasrootoranyotherprivilegeduser.Formoreinformation,see"RunningtheHelixserver(p4d)asanunprivilegeduser"onpage34.
Theserverrootcanbelocatedanywhere,buttheaccountthatrunsp4dmusthaveread,write,andexecutepermissionsontheserverrootandalldirectoriesbeneathit.Forsecuritypurposes,settheumask(1)file-creation-modemaskoftheaccountthatrunsp4dtoavaluethatdeniesotherusersaccesstotheserverrootdirectory.
Telling Helix Server applications which port to connect toThep4dserviceandHelixServerapplicationscommunicatewitheachotherusingTCP/IP.Whenp4dstarts,itlistens(bydefault)forplaintextconnectionsonport1666.HelixServerapplicationslikep4assume(alsobydefault)thatthecorrespondingp4dislocatedonahostnamedperforce,listeningonport1666,andthatcommunicationsareperformedinplaintext.
32
-
Communicating port information
Ifp4distolistenonadifferenthostorportand/oruseadifferentprotocol,eitherspecifytheconfigurationwiththe-pprotocol:host:portflagwhenyoustartp4d(asin,p4d -p ssl:perforce:1818),orbythecontentsoftheP4PORTenvironmentvariable.
Plaintextcommunicationsarespecifiedwithtcp:host:portandSSLencryptionisspecifiedwithssl:port.(TouseSSL,youmustalsosupplyorgenerateanx509certificateandprivatekey,andstoretheminasecurelocationonyourserver.See"UsingSSLtoencryptconnectionstoaHelixserver"onpage90fordetails.)
Thepreferredsyntaxforspecifyingtheportisthefollowing:
protocol:host:port
Therearesituations,forexampleifyouareusingmultiplenetworkcards,whereyoumightwanttospecifytheportonwhichtolistenusingsyntaxlikethefollowing:
P4PORT=ssl::1666
Theuseofthedoublecolondirectstheservertobindtoallavailablenetworkaddressesandtolistenonport1666.Thiscanbeusefulifthehosthasmultiplenetworkaddresses.
Note ToenableIPv6support,specifythewildcardaddresswithtwocolonswhenstartingp4d.Forexample:
$ p4d -p tcp64:[::]:1818
startsaPerforceservicethatlistensforplaintextconnections,onbothIPv6andIPv4transports,onport1818.Similarly,
$ p4d -p ssl64:[::]:1818
startsaPerforceservicethatrequiresSSLandlistensonIPv6andIPv4,and
$ p4d -p ssl6:[::]:1818
startsaPerforceservicethatrequiresSSLconnections,andlistensforIPv6connectionsexclusively.
See"IPv6supportandmixednetworks"onthefacingpageformoreinformationaboutIPv6andIPv4transports.
UnlikeP4ROOT,theenvironmentvariableP4PORTisusedbyboththePerforceserviceandtheHelixServerapplications,soitmustbesetbothonthemachinethathoststhePerforceserviceandonindividualuserworkstations.
Communicating port informationHelixServerapplicationsneedtoknowonwhatmachinethep4dserviceislistening,onwhichTCP/IPportp4dislistening,andwhethertocommunicateinplaintextoroverSSL.
33
-
IPv6 support and mixed networks
SeteachHelixServerusersP4PORTenvironmentvariabletoprotocol:host:port,whereprotocolisthecommunicationsprotocol(beginningwithssl:forSSL,ortcp:forplaintext),hostisthenameofthemachineonwhichp4disrunning,andportisthenumberoftheportonwhichp4dislistening.Forexample:
P4PORT Behaviortcp:server1:3435 HelixServerapplicationsconnectinplaintexttothePerforce
serviceonhostserver1listeningonport3435.
tcp64:server1:3435 HelixServerapplicationsconnectinplaintexttothePerforceserviceonhostserver1listeningonport3435.TheapplicationfirstattemptstoconnectoveranIPv6connection;ifthatfails,theapplicationattemptstoconnectviaIPv4.
ssl:example.org:1818 HelixServerapplicationsconnectviaSSLtothePerforceserviceonhostexample.orglisteningonport1818.
HelixServerapplicationsconnecttothePerforceserviceonahostnamedoraliasedperforcelisteningonport1666.Plaintextcommunicationsareassumed.
IfyouhaveenabledSSL,usersareshowntheserversfingerprintthefirsttimetheyattempttoconnecttotheservice.Ifthefingerprintisaccurate,userscanusethep4 trustcommand(eitherp4 trust -y,orp4 -p ssl:host:port trust -i fingerprint)toinstallthefingerprintintoafile(pointedtobytheP4TRUSTenvironmentvariable)thatholdsalistofknownandtrustedHelixserversandtheirrespectivefingerprints.IfP4TRUSTisunset,thisfileis.p4trustintheusershomedirectory.
IPv6 support and mixed networksAsofRelease2013.1,HelixServersupportsconnectivityoverIPv6networksaswellasoverIPv4networks.Fordetails,seeP4PORTinHelixVersioningEngineAdministratorGuide:Fundamentals.
Note Inmulti-serverenvironments,thenet.rfc3484configurable,whensetserver-side,alsocontrolsthebehaviorofhostresolutionwheninitiatingcommunicationsforserver-to-server,proxy,orbroker.
Running the Helix server (p4d) as an unprivileged userHelixServerdoesnotrequireprivilegedaccess.Forsecurityreasons,donotrunp4dasrootorotherwisegranttheownerofthep4dprocessroot-levelprivileges.
CreateanunprivilegedUNIXuser(forexample,perforce)tomanagep4dand(optionally)aUNIXgroupforit(forexample,p4admin).Usetheumask(1)commandtoensurethattheserverroot(P4ROOT)andallfilesanddirectoriescreatedbeneathitarewritableonlybytheUNIXuserperforce,and(optionally)readablebymembersoftheUNIXgroupp4admin.
34
https://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/P4PORT.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/P4TRUST.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/P4PORT.htmlhttps://www.perforce.com/perforce/doc.current/manuals/cmdref/#CmdRef/configurables.configurables.html#net.rfc3484
-
Running from inetd on UNIX
Underthisconfiguration,thePerforceservice(p4d),runningasUNIXuserperforce,canwritetofilesintheserverroot,butnousersareabletoreadoroverwriteitsfiles.Tograntaccesstothefilescreatedbyp4d(thatis,thedepotfiles,checkpoints,journals,andsoon)totrustedusers,youcanaddthetrusteduserstotheUNIXgroupp4admin.
Running from inetd on UNIXUnderanormalinstallation,thePerforceservicerunsonUNIXasabackgroundprocessthatwaitsforconnectionsfromusers.Tohavep4dstartuponlywhenconnectionsaremadetoit,usinginetdandp4d -i,addthefollowinglineto/etc/inetd.conf:
p4dservice stream tcp nowait username /usr/local/bin/p4d p4d -i -r
p4droot
andthenaddthefollowinglineto/etc/services:
p4dservice nnnn /tcp
where:
n p4dserviceistheservicenameyouchooseforthisHelixserver
n /usr/local/binisthedirectoryholdingyourp4dbinary
n p4drootistherootdirectory(P4DROOT)touseforthisHelixserver(forexample,/usr/local/p4d)
n usernameistheUNIXusernametouseforrunningthisHelixserver
n nnnnistheportnumberforthisHelixservertouse
The"extra"p4donthe/etc/inetd.conflinemustbepresent;inetdpassesthistotheOSasargv[0].Thefirstargument,then,isthe-iflag,whichcausesp4dnottorunasabackgroundprocess,butrathertoservethesingleclientconnectedtoitonstdin/stdout.(Thisistheconventionusedforservicesstartedbyinetd.)
Thismethodisanalternativetorunningp4dfromastartupscript.Itcanalsobeusefulforprovidingspecialservices;forexample,atPerforce,wehaveanumberoftestserversrunningonUNIX,eachdefinedasaninetdservicewithitsownportnumber.
Therearecaveatswiththismethod:
n inetdmaydisallowexcessiveconnections,soascriptthatinvokesseveralthousandp4commands,eachofwhichspawnsaninstanceofp4dviainetdcancauseinetdtotemporarilydisabletheservice.Dependingonyoursystem,youmightneedtoconfigureinetdtoignoreorraisethislimit.
n Thereisnoeasywaytodisabletheserver,sincethep4dexecutableisruneachtime;disablingtheserverrequiresmodifying/etc/inetd.confandrestartinginetd.
n TouseHelixServerwiththislicense,youwillneedtorequestaserverlicensethatdoesnotspecifyaport.ContactPerforcelicensingformoreinformation.
35
-
Starting the Perforce service
Note Forinformationaboutusingsystemdtolaunchservicesanddaemonsatboottimeseehttp://answers.perforce.com/articles/KB/10832.
Starting the Perforce serviceAfteryousetp4d'sP4PORTandP4ROOTenvironmentvariables,starttheservicebyrunningp4dinthebackgroundwiththecommand:
$ p4d &
Althoughtheexampleshownissufficienttorunp4d,youcanspecifyotherflagsthatcontrolsuchthingsaserrorlogging,checkpointing,andjournaling.
E x a m p l e Starting the Perforce serviceYoucanoverrideP4PORTbystartingp4dwiththe-pflag(inthisexample,listentoport1818onIPv6andIPv4transports),andP4ROOTbystartingp4dwiththe-rflag.Similarly,youcanspecifyajournalfilewiththe-Jflag,andanerrorlogfilewiththe-Lflag.Astartupcommandthatoverridestheenvironmentvariablesmightlooklikethis:
$ p4d -r /usr/local/p4root -J /var/log/journal -L /var/log/p4err
-p tcp64:[::]:1818 &
The-r,-J,and-Lflags(andothers)arediscussedin"Backupandrecovery"onpage132.ToenableSSLsupport,see"UsingSSLtoencryptconnectionstoaHelixserver"onpage90.Acompletelistofflagsisprovidedinthe"HelixVersioningEngine(p4d)Reference"onpage268.
Forinformationaboutthefilesthathavebeeninstalled,see"Installedfiles"onpage41.
Stopping the Perforce serviceToshutdownthePerforceservice,usethecommand:
$ p4 admin stop
OnlyaHelixServersuperusercanusep4 admin stop.
Restarting a running Perforce serviceTorestartarunningPerforceservice(forexample,toreadanewlicensefile),usethecommand:
$ p4 admin restart
OnlyaHelixServersuperusercanusep4 admin restart.OnUNIXplatforms,youcanalsousekill -HUPtorestarttheservice.
36
http://answers.perforce.com/articles/KB/10832
-
Windows installation
Windows installationToinstallHelixServeronWindows,usethePerforceinstallerfromtheDownloadspageofthePerforcewebsite:
http://www.perforce.com/downloads
UsethePerforceinstallerprogramtoinstallorupgradethePerforceservice,Perforceproxy,broker,ortheHelixServerCommand-LineClient.OtherHelixServerapplicationsonWindows,suchastheHelixVisualClient(P4V),aswellasthird-partyplug-ins,maybedownloadedandinstalledseparately.
ForanexampleofhowtoinstallHelixServeronWindows,see:
http://answers.perforce.com/articles/KB_Article/Example-Windows-Installation
Note IfyouhaveAdministratorprivileges,itisusuallybesttoinstallHelixServerasaservice.Ifyoudont,installitasaserver.
Windows services and serversInthismanual,thetermsPerforce Serviceandp4dareusedinterchangeablytoreferto"theprocesswhichprovidesversioningservicestoPerforceapplications"unlessthedistinctionbetweenaWindowsserverprocessoraserviceprocessisrelevant.
ThePerforceversioningservice(p4d)canbeconfiguredtorunasaWindowsservice(p4s.exe)processthatstartsatboottime,orasaserver(p4d.exe)processthatyouinvokemanuallyfromacommandprompt.TorunataskasaWindowsserver,theusermustbeloggedinbecauseshortcutsinausersstartupfoldercannotberununtilthatuserlogsin.
ThePerforceservice(p4s.exe)andthePerforceserver(p4d.exe)executablesarecopiesofeachother;theyareidenticalapartfromtheirfilenames.Whenrun,theexecutablesusethefirstthreecharactersofthenamewithwhichtheywereinvoked(eitherp4sorp4d)todeterminetheirbehavior.(Forexample,invokingcopiesofp4d.exenamedp4smyservice.exeorp4dmyserver.exeinvokeaserviceandaserver,respectively.)
Bydefault,thePerforceinstallerconfiguresPerforceasaWindowsservice..
Note OnWindows,directorypermissionsaresetsecurelybydefault;whenPerforcerunsasaWindowsserver,theserverrootisaccessibleonlytotheuserwhoinvokedp4d.exefromthecommandprompt.WhenPerforceisinstalledasaservice,thefilesareownedbytheLocalSystemaccount,andareaccessibleonlytothosewithAdministratoraccess.
37
http://www.perforce.com/downloads/complete_listhttp://answers.perforce.com/articles/KB_Article/Example-Windows-Installation
-
Installing the Perforce service on a network drive
ToallowthePerforceservicetorununderaregularuseraccount,makesurethattheuserhasread/writeaccesstotheregistrykeyandthattheuserhasaccesstothedirectorystructureunderP4ROOT.Foradditionalinformationseethefollowingarticle:
http://kbportal.perforce.com/article/3925
Installing the Perforce service on a network driveBydefault,thePerforceservicerunsunderthelocalSystemaccount.BecausetheSystemaccounthasnonetworkaccess,arealuseridandpasswordarerequiredinordertomakethePerforceserviceworkifthemetadataanddepotfilesarestoredonanetworkdrive.ThePerforceserviceisthenconfiguredwiththesupplieddataandrunasthespecifieduserinsteadofSystem.
Ifyouareinstallingyourserverrootonanetworkdrive,theHelixServerinstaller(helix-versioning-engine-x86.exe)requestsavalidcombinationofuseridandpasswordatthetimeofinstallation.Thisusermusthaveadministratorprivileges.
AlthoughthePerforceservicerunsreliablyusinganetworkdriveastheserverroot,thereisstillamarkedperformancepenaltyduetoincreasednetworktrafficandslowerfileaccess.Consequently,PerforcerecommendsthatthedepotfilesandHelixServerdatabaseresideonadrivelocaltothemachineonwhichthePerforceserviceisrunning.
Starting and stopping the Perforce serviceIfyouinstallHelixServerasaserviceunderWindows,theservicestartswheneverthemachineboots.UsetheServicesappletintheControl PaneltocontrolthePerforceservicesbehavior.
TostopaPerforceservice,usethecommand:
$ p4 admin stop
OnlyaHelixServersuperusercanusep4 admin stop.
ForolderrevisionsofHelixServer,shutdownservicesmanuallybyusingtheServicesappletintheControl Panel.
Forinformationaboutthefilesthathavebeeninstalled,see"Installedfiles"onpage41.
Multiple Perforce services under WindowsBydefault,theHelixServerinstallerforWindowsinstallsasingleHelixVersioningEngineasasingleservice.IfyouwanttohostmorethanoneHelixServerinstallationonthesamemachine(forinstance,oneforproductionandonefortesting),youcaneithermanuallystartHelixserversfromthecommandline,orusethePerforce-suppliedutilitysvcinst.exe,toconfigureadditionalPerforceservices.
38
http://kbportal.perforce.com/article/3925
-
Multiple Perforce services under Windows
Warning SettingupmultipleservicestoincreasethenumberofusersyousupportwithoutpurchasingmoreuserlicensesisaviolationofthetermsofyourPerforceEndUserLicenseAgreement.
UnderstandingtheprecedenceofenvironmentvariablesindeterminingPerforceconfigurationisusefulwhenconfiguringmultiplePerforceservicesonthesamemachine.Beforeyoubegin,readandunderstand"Windowsconfigurationparameterprecedence"onthefacingpage.
TosetupasecondPerforceservice:
1. CreateanewdirectoryforthePerforceservice.
2. Copytheserverexecutable,serviceexecutable,andyourlicensefileintothisdirectory.
3. CreatethenewPerforceserviceusingthesvcinst.exeutility,asdescribedintheexamplebelow.(Thesvcinst.exeutilitycomeswiththeHelixServerinstaller,andcanbefoundinyourHelixserverroot.)
4. Setuptheenvironmentvariablesandstartthenewservice.
WerecommendthatyouinstallyourfirstPerforceserviceusingtheHelixServerinstaller.ThisfirstserviceiscalledPerforceanditsserverrootdirectorycontainsfilesthatarerequiredbyanyotherPerforceservicesyoucreateonthemachine.
E x a m p l e Adding a second Perforce serviceYouwanttocreateasecondPerforceservicewitharootinC:\p4root2andaservicenameofPerforce2.ThesvcinstexecutableisintheserverrootofthefirstHelixServerinstallationyouinstalledinC:\perforce.
Verifythatyourp4d.exeexecutableisatRelease99.1/10994orgreater:
C:\> p4d -V
(Ifyouarerunninganolderrelease,youmustfirstdownloadamorerecentreleasefromwww.perforce.comandupgradeyourserverbeforecontinuing.)
CreateaP4ROOTdirectoryforthenewservice:
C:\> mkdir c:\p4root2
Copytheserverexecutables,bothp4d.exe(theserver)andp4s.exe(theservice),andyourlicensefileintothenewdirectory:
C:\> copy c:\perforce\p4d.exe c:\p4root2
C:\> copy c:\perforce\p4d.exe c:\p4root2\p4s.exe
C:\> copy c:\perforce\license c:\p4root2\license
Usesvcinst.exe(theserviceinstaller)tocreatethePerforce2service:
C:\> svcinst create -n Perforce2 -e c:\p4root2\p4s.exe -a
AfteryoucreatethePerforce2service,settheserviceparametersforthePerforce2service:
39
https://www.perforce.com/
-
Windows configuration parameter precedence
C:\> p4 set -S Perforce2 P4ROOT=c:\p4root2
C:\> p4 set -S Perforce2 P4PORT=1667
C:\> p4 set -S Perforce2 P4LOG=log2
C:\> p4 set -S Perforce2 P4JOURNAL=journal2
Finally,usethePerforceserviceinstallertostartthePerforce2service:
$ svcinst start -n Perforce2.
Thesecondserviceisnowrunning,andbothserviceswillstartautomaticallythenexttimeyoureboot.
Windows configuration parameter precedenceUnderWindows,HelixServerconfigurationparameterscanbesetinmanydifferentways.WhenaHelixServerapplication(suchasp4orP4V),oraHelixVersioningEngineprogram(p4d)startsup,itreadsitsconfigurationparametersaccordingtothefollowingprecedence:
1. ForHelixServerapplicationsoraHelixserver(p4d),command-lineflagshavethehighestprecedence.
2. ForaHelixserverserver(p4d),persistentconfigurablessetwithp4 configure.
3. TheP4CONFIGfile,ifP4CONFIGisset.
4. Userenvironmentvariables.
5. Systemenvironmentvariables.
6. TheWindowsuserregistry(orOSXuserpreferences)(setbyp4 set).
7. TheWindowssystemregistry(orOSXsystempreferences)(setbyp4 set -s).
WhenaPerforceservice(p4s)startsup,itreadsitsconfigurationparametersfromtheenvironmentaccordingtothefollowingprecedence:
1. Persistentconfigurablessetwithp4 configurehavethehighestprecedence.
2. Windowsserviceparameters(setbyp4 set -S servicename).
3. Systemenvironmentvariables.
4. TheWindowssystemregistry(orOSXuserpreferences)(setbyp4 set -s).
Userenvironmentvariablescanbesetwithanyofthefollowing:
n TheMS-DOSsetcommand
n TheAUTOEXEC.BATfile
n TheUser VariablestabundertheSystem PropertiesdialogboxintheControlPanel
Systemenvironmentvariablescanbesetwith:
n TheSystem VariablestabundertheSystem PropertiesdialogboxintheControlPanel.
40
-
Starting and stopping the Helix server
Starting and stopping the Helix serverTheserverexecutable,p4d.exe,isnormallyfoundinyourP4ROOTdirectory.Tostarttheserver,firstmakesureyourcurrentP4ROOT,P4PORT,P4LOG,andP4JOURNALsettingsarecorrect;thenrun:%P4ROOT%\p4d
TostartaserverwithsettingsdifferentfromthosesetbyP4ROOT,P4PORT,P4LOG,orP4JOURNAL,usep4dcommand-lineflags.Forexample:
C:\> C:\test\p4d -r c:\test -p 1999 -L c:\test\log -J
c:\test\journal
startsaHelixserverprocesswitharootdirectoryofc:\test,listeningtoport1999,loggingerrorstoc:\test\log,andwithajournalfileofc:\test\journal.Thep4dcommand-lineflagsarecase-sensitive.
TostoptheHelixserver,usethecommand:
C:\> p4 admin stop
Forinformationaboutthefilesthathavebeeninstalled,see"Installedfiles"below.
Support for long file namesSupportforlongfilenamesisenabledbydefaultinHelixServerversions2015.2orlater.ForolderversionsofHelixServer,youcanenablelongfilenamesupportontheserverwiththefilesys.windows.lfnconfigurable.
Note Theserverrootorclientrootcannotbealongpath.
Setfilesys.windows.lfnto1tosupportfilenameslongerthan260charactersonWindowsplatforms.Afilenamelengthofupto32,767charactersisallowed.Eachcomponentofthepathislimitedto255characters.
Tosetontheserver,useacommandlikethefollowing:
C:\> p4 configure set filesys.windows.lfn=1
Dependingonthedepthofyourworkspacepath,youmightalsoneedtosetthisconfigurableontheclientand/orproxy(whichactsasaclient).Tosettheconfigurableforaproxy,useacommandlikethefollowing:
C:\> p4 set -S "Perforce Proxy" P4DEBUG=filesys.windows.lfn=1
Installed filesInstallationaddsthreetypesoffilestotheHelixserverhost:
41
-
Upgrading the Perforce service
n Databasefiles
n TheJournalfile
n TheHelixServerbinary
ThedatabasefilesandtheJournalfileareplacedintherootdirectoryoftheHelixserver.Eventually,asusersandadministratorsworkwithHelixserver,otherfilesareaddedtotheHelixserverrootdirectory(P4ROOT):usersarchivedfiles,checkpointfile,andlogfiles.
TheHelixServerbinaryisalsoinstalled,asshowninthefollowingtable.
Operating system
Location
Linuxdownload
Wherevertheadministratorputsit.Usually/usr/local/bin/p4dor,ifinstalledviapackages,/opt/perforce/bin/p4d
Windowsdownload
Wheretheadministratorputsit.Bydefaultitisdownloadedtothefollowingdirectory:C:\Program Files\Perforce\Server\p4d
MacOSX Wheretheadministratorputsit.Usually/usr/bin/p4dor/user/local/bin/p4d
Upgrading the Perforce serviceYoumustbackupyourHelixServerinstallation(see"Backupprocedures"onpage138)aspartofanyupgradeprocess.
Warning BeforeyouupgradethePerforceservice,alwaysreadthereleasenotesassociatedwithyourupgradedinstallation.
Inordertoupgradefrom2013.2(orearlier)to2013.3(orlater),youmustrestorethedatabasefromacheckpoint.See"Checkpointsfordatabasetreerebalancing"onpage195foranoverviewoftheprocessand"UpgradingHelixServer-between2013.2and2013.3"onpage44forinstructionsspecifictothisupgrade.
Inreplicatedanddistributedenvironments(seeHelix Versioning Engine Administrator Guide: Multi-Site Deployment),allreplicasmustbeatthesamereleaselevelasthemaster.Anyfunctionalitythatrequiresanupgradeforthemasterrequiresanupgradeforthereplica,andviceversa.
42
http://www.perforce.com/perforce/doc.current/manuals/p4dist/index.htmlhttp://www.perforce.com/perforce/doc.current/manuals/p4dist/index.html
-
Using old Helix Server applications after an upgrade
Using old Helix Server applications after an upgradeAlthougholderHelixServerapplicationsgenerallyworkwithnewerversionsofHelixServer,somefeaturesinnewserverreleasesrequireupgradestoHelixServerapplications.Ingeneral,userswitholderapplicationsareabletousefeaturesavailablefromHelixServerattheuserapplicationsreleaselevel,butarenotabletousethenewfeaturesofferedbysubsequentupgradestotheservice.
Helix Server Licensing and upgradesToupgradeHelixServertoanewerversion,yourHelixServerlicensefilemustbecurrent.ExpiredlicensesdonotworkwithupgradedversionsofHelixServer.
Upgrading Helix ServerFollowtheinstructionsinthissectionifbothyouroldandnewversionsofHelixServerare2013.3orlater.
ReadtheRelease Notesforcompleteinformationonupgradeprocedures.
Warning Inordertoupgradefrom2013.2(orearlier)to2013.3(orlater),youmustrestorethedatabasefromacheckpoint.See"Checkpointsfordatabasetreerebalancing"onpage195foranoverviewoftheprocess,and"UpgradingHelixServer-between2013.2and2013.3"onthefacingpageinstructionsspecifictothisupgrade.
Ingeneral,HelixServerupgradesrequirethatyou:
1. Runthep4d -xvandp4d -xxcommandstoensurethatdb.*filesareOKbeforetheupgrade.
2. Verifyyourfiles,see"Verifyingfilesduringserverupgrades"onpage45formoreinformation.
3. Makeacheckpointandbackupyouroldinstallation.(See"Backupprocedures"onpage138.)
4. StopthePerforceservice(p4 admin stop).
5. Replacethep4dexecutablewiththeupgradedversion.
OnUNIX,replacetheoldversionofp4dwiththenewversiondownloadedfromthePerforcewebsite.OnWindows,usetheHelixServerinstaller(helix-versioning-engine-x86.exe);theinstallerautomaticallyreplacestheexecutable.
Important ThisstepincludesarunofWindowsinstallerandwillfailifyourupgraderequiresstep6.Ifthisisthecase,anadminusershouldreviewtheserver'slogfiletofindoutwhyithasnotrestarted.
43
http://www.perforce.com/perforce/doc.current/user/relnotes.txt
-
Upgrading Helix Server - between 2013.2 and 2013.3
6. Someupgrades(installationswithmorethan1000changelists,orupgradeswithcertaindatabasechanges)mayrequirethatyoumanuallyupgradethedatabasebyrunning:
p4d -r server_root -J journal_file -xu
Thiscommandmaytakeconsiderabletimetocomplete.Youmusthavesufficientdiskspacetocompletetheupgrade.
7. RestartthePerforceservicewithyoursitesusualparameters.
Ifyouhaveanyquestionsordifficultiesduringanupgrade,contactPerforcetechnicalsupport.
Upgrading Helix Server - between 2013.2 and 2013.3Followtheinstructionsinthissectionifyouroldversionis2013.2orearlierandyournewversionis2013.3orlater.
HelixServer2013.3containsmajorchangestothedatabaseimplementation.Thesechangesallowforincreasedconcurrencyandscalability,andincreasethesizelimitforthedb.*databasefilesto16TB.
Althoughthedb.*databasefileformathaschanged,thecheckpointandjournalfileformatsareidentical.Inordertoupgradefrom2013.2(orearlier)to2013.3(orlater),youmustrestorethedatabasefromacheckpoint.Todothis:
1. StopthePerforceservice(p4 admin stop).
2. Makeacheckpointandbackupyouroldinstallation.(see"Backupprocedures"onpage138)
3. Ifafilecalledtiny.dbexistsinyouroldserverroot,youmustbackitupseparatelybyrunningthefollowingcommandwiththeoldp4d:
p4d -xf 857 > tiny.ckp
4. Removetheolddb.*files,orpreferably,movethemtoasafelocationintheeventthattheupgradefails.
mv your_root_dir /db.* /tmp
Theremustbenodb.*filesintheP4ROOTdirectorywhenyourebuildadatabasefromacheckpoint.Althoughtheolddb.*fileswillnotbeusedagain,itsgoodpracticenottodeletethemuntilyourecertainyourupgradewassuccessful.
5. Removetherdb.lbrfile,ifitexists.
Therdb.lbrfilekeepstrackoffilesthatneedtobetransferredtothe(local)replica,andmaybecomeoutofdatewhiletheupgradeisunderway.NotethatthisfileonlyexistsifyourPerforceservicewasconfiguredasareplica.
6. Replacetheold(2013.2orearlier)p4dexecutablewiththenew(2013.3orlater)p4dexecutable.
Donotrunp4d -xuafterreplacingp4datthistime.Inthisupgradescenario,youarenotupgradinganexistingdatabase,youhaveremoveditcompletelyandwillrebuilditfromthecheckpointthatyoujusttook.
44
-
Verifying files by signature
7. Usetheupgradedp4dtoreplaythecheckpointandrebuildthenewdatabasetables:
p4d -r $P4ROOT -jr checkpoint_file
8. IfyoursiteuseslocalizedservermessagesfromamessagefileobtainedthroughPerforcetechnicalsupport,retrievetheoriginalmessage.txtfileandre-createdb.messageinthenewdatabaseformatbyrunningthefollowingcommandwiththenewp4d:
p4d -jr /fullpath/message.txt
See"Localizingservererrormessages"onpage58formoreinformation.
9. Ifyoucreatedatiny.ckpfileaspartofyourbackupprocess,restoretiny.dbbyrunningthefollowingcommandwiththenewp4d:
$ p4d -xf 857 tiny.ckp
10. Runp4d -xuagainsttheHelixServerdatabasetoupdatethedatabaseschema:
$ p4d -r $P4ROOT -J myJournal -xu
11. RestartthePerforceserviceandresumeoperations.
Verifying files by signatureHelixServeradministratorscanusethep4 verify filenamescommandtovalidatestoredMD5digestsofeachrevisionofthenamedfiles.Thesignaturescreatedwhenusersstorefilesinthedepotcanlaterbeusedtoconfirmproperrecoveryincaseofacrash:ifthesignaturesoftherecoveredfilesmatchthepreviouslysavedsignatures,thefileswererecoveredaccurately.IfanewsignaturedoesnotmatchthesignatureintheHelixServerdatabaseforthatfilerevision,HelixServerdisplaysthecharactersBAD!afterthesignature.
Itisgoodpracticetorunp4 verifybeforeperformingyournightlysystembackups,andtoproceedwiththebackuponlyifp4 verifyreportsnocorruption.
Forlargeinstallations,p4 verifycantakesometimetorun.Theserverisalsounderheavyloadwhilefilesarebeingverified,whichcanimpacttheperformanceofotherHelixServercommands.Administratorsoflargesitesmightwanttoperformp4 verifyonaweeklybasis,ratherthananightlybasis.
IfyoueverseeaBAD!signatureduringap4 verifycommand,yourdatabaseorversionedfilesmightbecorrupt,andyoushouldcontactPerforceTechnicalSupport.
Verifying files during server upgradesItisgoodpracticetousep4 verifyasfollowsbeforeandafterserverupgrades:
1. Beforetheupgrade,run:
$ p4 verify -q //...
toverifytheintegrityofyourserverbeforetheupgrade.
2. Takeacheckpointandcopythecheckpointandyourversionedfilestoasafeplace.
45
-
Release and license information
3. Performtheserverupgrade.
4. Aftertheupgrade,run:
$ p4 verify -q //...
toverifytheintegrityofyournewsystem.
Release and license informationThePerforceversioningserviceislicensedaccordingtohowmanystandardusersitsupports.TherearethreetypesofPerforceusers:standardusers,operatorusers,andserviceusers.
n AstandarduserisatraditionaluserofPerforce.
Standardusersarethedefault,andeachstandarduserconsumesonePerforcelicense.
n Anoperatoruserisintendedforhumanorautomatedsystemadministrators.
AnoperatoruserdoesnotrequireaPerforcelicense.
n Aserviceuserisusedforserver-to-serverauthentication,whetherinthecontextofremotedepots(see"Remotedepotsanddistributeddevelopment"onpage82)orindistributedenvironments.
Serviceusersdonotrequirelicenses,butarerestrictedtoautomatedinter-servercommunicationprocessesinreplicatedandmulti-serverenvironments.
Licensinginformationiscontainedinafilecalledlicenseintheserverrootdirectory.ThelicensefileisaplaintextfilesuppliedbyPerforceSoftware.Withoutthelicensefile,theservicelimitsitselftoeither20usersand20clientworkspaces(andunlimitedfiles),ortoanunlimitednumberofusersandworkspaces(butwithalimitof1000files).
YoucanupdateanexistinglicensefilewithoutstoppingPerforcebyusingthep4 licensecommand.See"Addingnewlicensedusers"onpage164fordetails.
n Iftheserviceisrunning,anyusercanusep4 infotoviewbasiclicensinginformation.Administratorscanusep4 license -utoobtainmoredetailedinformationabouthowmanyusersandfilesareinuse.
n Iftheserviceisdown,youcanalsoobtainlicensinginformationbyrunningp4d -Vfromtheserverrootdirectorywherethelicensefileresides,orbyspecifyingtheserverrootdirectoryeitheronthecommandline(p4d -V -r server_root)orintheP4ROOTenvironmentvariable.
Theserverversionisalsodisplayedwhenyouinvokep4d -Vorp4 -V.
46
-
Configuring the serverThePerforceserviceishighlyconfigurableandthisisaccomplishedthroughthesettingofserver,client,andproxyconfigurables.Availableconfigurablesnumberinthehundreds,anditisprobablybesttosetthemasyoucontinuetoworkwiththeserver.Thischapterlimitsitselftodescribingtheconfigurablesyoumightinitiallywanttoconfigurebeforeyoubeginworkingwiththeserver.
Thefollowingareasarecovered:
n Enablingdistributedversioning
n Usingp4typemaptodetermineafilestypeandtoimplementsite-wideexclusivelocking
n Definingadditionaldepots
n Managingclientrequests
n ManagingcasesensitivityandUnicodeinstallations
n Configuringlogging
n ConfiguringP4Vsettings
Forcompleteinformationaboutusingthep4 configurecommandandallavailableserver,client,andproxyconfigurables,seeP4 Command Referenceandp4 help configurables.
Enabling distributed versioningIfyouneedtoenablethetransferoffilesbetweenauserslocalrepositoryandthesharedrepository,youmustsetthefollowingconfigurables:server.allowfetchandserver.allowpush.
Defining filetypes with p4 typemapHelixServerusesthefilesys.binaryscanconfigurabletodeterminehowmanybytestoexaminewhendeterminingifafileisoftypetextorbinary.Bydefault,filesys.binaryscanis65536;ifthehighbitisclearinthefirst65536bytes,HelixServerassumesittobetext;otherwise,itisassumedtobebinary.Filescompressedinthe.zipformat(including.jarfiles)arealsoautomaticallydetectedandassignedthetypeubinary.
Althoughthisdefaultbehaviorcanbeoverriddenbytheuseofthe-t filetypeflag,itseasyforuserstooverlookthisconsideration,particularlyincaseswherefiles'typesareusually(butnotalways)detectedcorrectly.Certainfileformats,suchasRTF(RichTextFormat)andAdobePDF(PortableDocumentFormat),canstartwithaseriesofcommentfieldsorothertextualdata.Ifthesecommentsaresufficientlylong,suchfilescanbeerroneouslydetectedbyHelixServerasbeingoftypetext.
47
http://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html
-
Defining filetypes with p4 typemap
Thep4 typemapcommandsolvesthisproblembyenablingsystemadministratorstosetupatablethatlinksHelixServerfiletypeswithfilenamespecifications.Ifanentryinthetypemaptablematchesafilebeingadded,itoverridesthefiletypethatwouldotherwisebeassignedbytheHelixServerapplication.Forexample,totreatallPDFandRTFfilesasbinary,usep4 typemaptomodifythetypemaptableasfollows:
Typemap:
binary //....pdf
binary //....rtf
Thefirstthreeperiods("...")inthespecificationareaHelixServerwildcardspecifyingthatallfilesbeneaththerootdirectoryaretobeincludedinthemapping.Thefourthperiodandthefileextensionspecifythatthespecificationappliestofilesendingin.pdf(or.rtf).
ThefollowingtablelistsrecommendedHelixServerfiletypesandmodifiersforcommonfileextensions.
File type Helix Server file type Description.asp text Activeserverpagefile
.avi binary+F VideoforWindowsfile
.bmp binary Windowsbitmapfile
.btr binary Btrievedatabasefile
.cnf text Conferencelinkfile
.css text Cascadingstylesheetfile
.doc binary MicrosoftWorddocument
.dot binary MicrosoftWordtemplate
.exp binary+w Exportfile(MicrosoftVisualC++)
.gif binary+F GIFgraphicfile
.gz binary+F Gzipcompressedfile
.htm text HTMLfile
.html text HTMLfile
.ico binary Iconfile
.inc text ActiveServerincludefile
.ini text+w Initialapplicationsettingsfile
.jpg binary JPEGgraphicfile
.js text JavaScriptlanguagesourcecodefile
48
-
Defining filetypes with p4 typemap
File type Helix Server file type Description.lib binary+w Libraryfile(severalprogramminglanguages)
.log text+w Logfile
.mpg binary+F MPEGvideofile
.pdf binary AdobePDFfile
.pdm text+w SybasePowerDesignerfile
.ppt binary MicrosoftPowerPointfile
.prefab binary Unity3Dfile
.xls binary MicrosoftExcelfile
Usethefollowingp4 typemaptabletomapallofthefileextensionstotheHelixServerfiletypesrecommendedintheprecedingtable.
# Perforce File Type Mapping Specifications.
#
# TypeMap: a list of filetype mappings; one per line.
# Each line has two elements:
# Filetype: The filetype to use on 'p4 add'.
# Path: File pattern which will use this filetype.
# See 'p4 help typemap' for more information.
TypeMap:
text //....asp
binary+F //....avi
binary //....bmp
binary //....btr
text //....cnf
text //....css
binary //....doc
binary //....dot
binary+w //....exp
binary+F //....gif
binary+F //....gz
text //....htm
text //....html
binary //....ico
49
-
Implementing site-wide exclusive locking with p4 typemap
text //....inc
text+w //....ini
binary //....jpg
text //....js
binary+w //....lib
text+w //....log
binary+F //....mpg
binary //....pdf
text+w //....pdm
binary //....ppt
binary //....xls
Ifafiletyperequirestheuseofmorethanonefiletypemodifier,specifythemodifiersconsecutively.Forexample,binary+lFS10referstoabinaryfilewithexclusive-open(l),storedinfull(F)ratherthancompressed,andforwhichonlythemostrecenttenrevisionsarestored(S10).
Formoreinformation,seethep4 typemappageintheP4 Command Reference.
Implementing site-wide exclusive locking with p4 typemapBydefault,HelixServersupportsconcurrentdevelopment,butenvironmentsinwhichonlyonepersonisexpectedtohaveafileopenforeditatatimecanimplementsite-wideexclusivelockingbyusingthe+l(exclusiveopen)modifierasapartialfiletype.Ifyouusethefollowingtypemap,the+lmodifierisautomaticallyappliedtoallnewlyaddedfilesinthedepot:
Typemap:
+l //depot/...
Ifyouusethistypemap,anyfilesyourusersaddtothedepotafteryouupdateyourtypemapautomaticallyhavethe+lmodifierapplied,andmayonlybeopenedforeditbyoneuseratatime.Thetypemaptableappliesonlytonewadditionstothedepot;afteryouupdatethetypemaptableforsite-wideexclusiveopen,filespreviouslysubmittedwithout+lmustbeopenedforeditwithp4 edit -t+l filenameandresubmitted.Similarly,userswithfilesalreadyopenforeditmustupdatetheirfiletypeswithp4 reopen -t+l filename.
Defining depotsBydefault,thestandarddepotDepotiscreatedintheserverwhentheserverstartsup.Dependingonyourusersneeds,youcanchangeitsnameandyoucancreateadditionaldepotstoserveyourneeds:
n Additionalstandarddepotsallowyoutoorganizeusersworkinrelevantcategories.
n Streamdepotsarededicatedtotheorganizationandmanagementofstreams.
n Remotedepotsareusedtofacilitatethesharingofcode.
50
http://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html
-
Managing client requests
n Aspecdepotisusedtotrackchangestouser-editedformssuchasworkspacespecifications,jobs,branchmappings,andsoon.
n Archivedepotsareusedtoofflinestorageofinfrequentlyneededcontent.
n Unloaddepotsareusedtoofflinestorageofinfrequentlyneededmetadata.
Pleasesee"Workingwithdepots"onpage77formoreinformation.
Managing client requestsThefollowingsectionsdescribeconfigurationoptionsthatrelatetohandlingclientrequests.
Using P4PORT to control access to the serverUndermostcircumstances,yourHelixserversP4PORTsettingconsistsofaportnumber.UsersmustknowtheIPaddress(orbeabletoresolveitfromahostname)oftheHelixserverinordertoconnecttoit.
ThevalueofP4PORThowever,canalsoincludeanIPaddressorhostnamethatresolvestoanIPaddress.YoucansetP4PORTtoconfigurethefollowingpossibilities:
n P4PORT=portnumber
Inthiscase,theserverlistensonthespecifiedportforeveryIPaddressassociatedwiththishost.
n P4PORT=ipaddress|hostname:portnumber
Inthiscase,theserverlistensonthespecifiedportforthespecifiedIPaddressorhostname,anditignoresrequeststoanyotherIPaddress.
n P4PORT=localhost:portnumber
Inthiscase,theserverlistensonthespecifiedportforrequeststhatoriginatefromusersonthishost.ThisforcestheHelixservertoignoreallnon-localconnectionrequests.
P4PORTmightalsospecifyaprotocol(protocol:address:port),whichfurtherrestrictspossibleconnectionstothoseusingthespecifiedprotocol.Forcompleteinformation,seethedescriptionoftheP4PORTvariableintheP4 Command Reference.
Requiring minimum client revisionsHelixserveroffersamechanismtocontrolwhichrevisionsofclientapplicationsareabletoconnecttoit.
Torequireaminimumrevision,settheconfigurablesminClienttotheappropriaterevision,and(optionally)setminClientMessagetotheerrormessagedisplayedwhenusersofolderapplicationsconnecttotheserver.
Forexample:
51
http://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html
-
Rejecting client connection requests
$ p4 configure set minClient=2010.2
$ p4 configure set minClientMessage="Please upgrade to 2010.2 or
higher"
Rejecting client connection requestsYoucansettherejectListconfigurabletoblockoneormoreclientprogramsfromaccessingtheHelixserver.Bydefault,allclientsmayaccesstheserver.
ThesimpleversionofthesyntaxforsettingrejectLististhefollowing:
rejectList = progName [[,progName]...]
ThesyntaxofprogNameisthefollowing:
progName[,version=versionName]
Forexample,thefollowingcommandblocksrequestsfromallcommandlineclients.
$ p4 configure set "rejectList = p4"
Thefollowingcommandblocksrequestsfromcommandlineclientsversion13.1and13.2.
$ p4 configure set "rejectList = p4, version=13.1, p4,
version=13.2"
Note BlockingspecificversionsofP4Vclientsisslightlydifferent.Fordetails,see"BlockingP4VclientsfromaccessingHelixserver"onthefacingpage.
Youmaynotuseanywildcardcharacterintheprogramnameparameter.
ThecommaisusedasthedefaultseparatorfortheelementsinrejectList.Iftheversionnumberfortheprogramyouareexcludingincludesacomma,youmustuseaslightlymorecomplicatedsyntaxtodefinerejectList:
rejectList = separator=char progName [[char progName]...]
Ifyoudefinechartobe#,thepreviouscommandlinewouldlooklikethis:
$ p4 configure set "rejectList = separator=# p4, version=13,1# p4#
version=13,2"
Therejectedconnectionisneverlogged;thelogwillnotincludeinformationabouttheconnectionattempt.
Youcanspecifyaversionusingabuildnumber;forexample:
$ p4 configure set "rejectList = p4, version=1221235"
Oryoucanuseplatforminformation;forexample:
52
-
Disabling user metrics collection prompt
$ p4 configure set "rejectList = p4, version=DARWIN90X86_64"
Oryoucanblockforeithercondition;forexample:
$ p4 configure set "rejectList = p4, version=1221235, p4,
version=DARWIN90X86_64"
Notetheuseofquotationmarksforstringsthatincludespaces!
Important Ifyouaccidentallylockoutkeyclientsneededtoaccesstheserver,usethefollowingcommandtounsettheconfigurable:
$ p4d -r P4ROOT '-cunset rejectList'
Blocking P4V clients from accessing Helix serverYoucanonlyusetheversion=fieldintherejectListconfigurableforclientsthatspecifytheirversionintheversionfield.P4Vdoesnotpassaversionstring.Instead,itpassesitsversioninformationontheprogramstring.Therefore,therejectListconfigurabledoesnotworkasexpectedwithP4V.
WhenyouconnecttoHelixserverwiththecommandlineclient,theclientspecifiesitsprogram nameasp4anditsversionas,forexample,2015.1/NTX64/1227227.However,whenyouconnectwithP4V,P4VtellsHelixserverthatitsprogram nameisP4V/MACOSX106X86/2012.3/578478anditsversionisNULL.
ToblockspecificP4Vversions,youcanspecifystringstosearchinstead.Forexample,toblockP4Vclientsversion2015.2onWindowsandLinuxplatformsaswellasversion2012.1onWindows,runthefollowingcommand:
$ p4 configure set "rejectList=P4V/NTX64/2015.2, P4V/NTX86/2012.1,
P4V/LINUX26X86_64/2015.2"
Disabling user metrics collection promptP4Vusershavetheoptionofenablingusermetricscollection.Bydefault,nodataiscollected.Thefirsttimeauserconnectstotheserver,apromptisdisplayedaskingiftheuserwantstosendPerforceanonymoususerdata.Suchdataincludesinformationaboutsystemhardware,non-defaultuserpreferences,andsoon.TheusercansubsequentlychangecollectionpreferenceusingthePreferencesmenu.
Ifyoudonotwantuserstoseetheprompt,youcansetapropertyontheserverasfollows:
$ p4 property -a -n P4.DataAnalyticsPrompt -v off
53
-
Case sensitivity and multi-platform development
Thispreventsusersfromseeingtheprompt.However,thisisanincompletesolutionbecauseifusersconnecttoaserverthatdoesnothavethepropertyset,theywillseethepromptandmightchoosetosendthedata.Tofullydisablethisfeature,youwillneedtohaveITshutdownanyoutgoingPOSTrequeststoudc.perforce.com.
Case sensitivity and multi-platform developmentVeryearly(pre-97.2)releasesofHelixServertreatedallfilenames,pathnames,anddatabaseentitynameswithcasesignificance,whethertheserverwasrunningonUNIXorWindows.
Forexample,//depot/main/file.cand//depot/MAIN/FILE.Cweretreatedastwocompletelydifferentfiles.ThiscausedproblemswhereusersonUNIXwereconnectingtoaHelixVersioningEnginerunningonWindowsbecausethefilesystemunderlyingtheservercouldnotstorefileswiththecase-variantnamessubmittedbyUNIXusers.
Inrelease97.3,thebehaviorwaschanged,andonlytheUNIXserversupportscase-sensitivenames.However,therearestillsomecase-sensitivityproblemsthatuserscanencounterwhensharingdevelopmentprojectsacrossUNIXandWindows.
Ifyouarerunningapre-97.2serveronWindows,pleasecontactsupport@perforce.comtodiscussupgradingyourserveranddatabase.
Forcurrentreleasesoftheserver:
n TheHelixVersioningEngineonUNIXsupportscase-sensitivenames.
n TheHelixVersioningEngineonWindowsignorescasedifferences.
n Caseisalwaysignoredinkeyword-basedjobsearches,regardlessofplatform.
Thefollowingtablesummarizestheserules.
Case-sensitive UNIX server Windows serverPathnamesandfilenames Yes No
Databaseentities(workspaces,labels,andsoon.) Yes No
Jobsearchkeywords No No
TofindoutwhatplatformyourHelixVersioningEnginerunson,usep4 info.
Helix server on UNIXIfyourHelixVersioningEngineisonUNIX,andyouhaveusersonbothUNIXandWindows,yourUNIXusersmustbeverycarefulnottosubmitfileswhosenamesdifferonlybycase.AlthoughtheUNIXservercansupportthesefiles,whenWindowsuserssynctheirworkspaces,theyllfindfilesoverwritingeachother.
54
mailto:[email protected]
-
Helix server on Windows
Conversely,Windowsuserswillhavetobecarefultousecaseconsistentlyinfilenamesandpathnameswhenaddingnewfiles.Theymightnotrealizethatfilesaddedas//depot/main/one.cand//depot/MAIN/two.cwillappearintwodifferentdirectorieswhensyncedtoaUNIXusersworkspace.
TheUNIXHelixserveralwaysrespectscaseinclientnames,labelnames,branchviewnames,andsoon.WindowsusersconnectingtoaUNIXservershouldbeawarethatthelowercasedworkstationnamesareusedasthedefaultnamesfornewclientworkspaces.Forexample,ifanewusercreatesaclientworkspaceonaWindowsmachinenamedROCKET,thisclientworkspaceisnamedrocketbydefault.IftheuserlatersetsP4CLIENTtoROCKET(orRocket),theHelixserverwilldisplayamessagethattheworkspaceisundefined.TheusermustsetP4CLIENTtorocket(orunsetit)tousetheclientworkspacedefined.
Helix server on WindowsIfyourHelixVersioningEngineisrunningonWindows,yourUNIXusersmustbeawarethatitwillstorecase-variantfilesinthesamenamespace.
Forexample,userswhotrysomethinglikethis:
C:\> p4 add dir/file1
C:\> p4 add dir/file2
C:\> p4 add DIR/file3
shouldbeawarethatallthreefileswillbestoredinthesamedepotdirectory.ThedepotpathnamesandfilenamesassignedtotheWindowsserverwillbethosefirstreferenced.(Inthiscase,thedepotpathnamewouldbedir,andnotDIR.)
Setting up and managing Unicode installationsThefollowingsectionsdescribethebenefitsofrunningtheHelixserverinUnicodemodeandexplainhowyouenablethismode.
Warning ConvertingaservertoUnicodemodeisaone-wayoperation!YoucannotrestoreaUnicodeservertoitspreviousstate.
OverviewTheHelixVersioningEnginecanberuninUnicodemodetoconvertcertainelementsfromtheirunicoderepresentationontheserver,totheparticularcharactersetusedonclientsandtriggersthatcommunicatewiththeserver.Thefollowingelementsareconverted:
55
-
Setting up a server for Unicode
n FilenamesordirectorynamesthatcontainUnicodecharacters
n Helixserveridentifiers(forexample,usernames)andspecifications(forexample,changelistdescriptionsorjobs)thatcontainUnicodecharacters
IfyouneedtomanagetextualfilesthatcontainUnicodecharacters,butdonotneedthefeatureslistedabove,youdonotneedtorunyourserverinUnicodemode.Forsuchinstallations,assigntheHelixServerutf16filetypetotextualfilesthatcontainUnicodecharacters.
n unicodefilesandmetadata.Theseareconvertedtothecharactersetconfiguredontheusersmachine.
TheHelixserveralsoverifiesthattheunicodefilesandmetadatacontainvalidUTF-8characters.
Normally,settingtheserverinUnicodemodeshouldautomaticallyconfiguretheappropriaterenderingforeachclient,independentlyoftheplatformwhereitruns.However,therearesomecasesinwhichyoumightalsohavetoconfiguretheclient.Thefollowingsubsectionsdescribehowyousetuptheserverandtheclientifneeded,andoffersometroubleshootingtips.
Inadditiontoaffectingtheclient,Unicodesettingsalsoaffecttriggerscriptsthatcommunicatewiththeserver.Youshouldcheckyourtriggersuseoftheelementsnotedabove(filenames,HelixServeridentifiers,etc.)andmakesurethattheseareconsistentwiththecharactersetusedbytheserver.
Note Allp4derrorandinfologsareinUTF8foraserverinunicodemode.YouneedanUTF8consoleoreditortoproperlyrenderthisloginformation.
Setting up a server for UnicodeHowyouconfigureaUnicode-modeserverandtheworkstationsthataccessit,dependsonwhetheryouarestartingaserverforthefirsttimeorwhetheryouareconvertinganexistingnon-unicodeservertounicodemode.Thefollowingsectionsexplaineachusecase.
Note ThePerforceservicelimitsthelengthsofstringsusedtoindexjobdescriptions,tospecifyfilenamesandviewmappings,andtoidentifyclientworkspaces,labels,andotherobjects.Themostcommonlimitis2,048bytes.BecausenobasicUnicodecharacterexpandstomorethanthreebytes,youcanensurethatnonameexceedsthislimitbylimitingthelengthofobjectnamesandviewspecifi