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

[email protected].

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:


deb http://package.perforce.com/apt/ubuntu/ trusty release

c. For Ubuntu 16.04:


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.


a. For Ubuntu:

$ sudo apt-get update

$ sudo apt-get install helix-p4d


# 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.


a. For Ubuntu:


$ sudo apt-cache madison helix-p4d


# yum --showduplicates list helix-p4d

30

UNIX non-package installation

3. Install an updated package.

Note Toupdateadifferentpackage,substituteitsnameforhelix-p4dinthecommandsbelow.

Thecommandtoupdateisthesameusedtoinstallinitially.


a. For Ubuntu:


$ sudo apt-get install helix-p4d


# 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


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


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


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

Helix Versioning Engine Administrator Guide: Fundamentals - 2016.2

Documents

Transcript of Helix Versioning Engine Administrator Guide: Fundamentals - 2016.2