<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 2.0.22">
<meta name="author" content="Perforce Professional Services">
<title>SDP Legacy Upgrade Guide (for Unix)</title>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700">
<style>
/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment the following line when using as a custom stylesheet */
/* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
html{font-family:sans-serif;-webkit-text-size-adjust:100%}
a{background:none}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
b,strong{font-weight:bold}
abbr{font-size:.9em}
abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
dfn{font-style:italic}
hr{height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
audio,video{display:inline-block}
audio:not([controls]){display:none;height:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type=checkbox],input[type=radio]{padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,::before,::after{box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:0}
p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ul.square{list-style-type:square}
ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
table thead,table tfoot{background:#f7f8f7}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt{background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
:not(pre).nobreak{word-wrap:normal}
:not(pre).nowrap{white-space:nowrap}
:not(pre).pre-wrap{white-space:pre-wrap}
:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
pre>code{display:block}
pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child{border-bottom:1px solid #dddddf;padding-bottom:8px}
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
details{margin-left:1.25rem}
details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
details>summary::-webkit-details-marker{display:none}
details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
.sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child,.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
.listingblock>.content{position:relative}
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.prettyprint{background:#f7f7f8}
pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
pre.prettyprint li code[data-lang]::before{opacity:1}
pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
table.linenotable td.code{padding-left:.75em}
table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
pre.pygments span.linenos{display:inline-block;margin-right:.75em}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
td.tableblock>.content>:last-child{margin-bottom:-1.25em}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>*>tr>*{border-width:1px}
table.grid-cols>*>tr>*{border-width:0 1px}
table.grid-rows>*>tr>*{border-width:1px 0}
table.frame-all{border-width:1px}
table.frame-ends{border-width:1px 0}
table.frame-sides{border-width:0 1px}
table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
li>p:empty:only-child::before{content:"";display:inline-block}
ul.checklist>li>p:first-child{margin-left:-1em}
ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
td.hdlist2{word-wrap:anywhere}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active,#footnotes .footnote a:first-of-type:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background:#00fafa}
.black{color:#000}
.black-background{background:#000}
.blue{color:#0000bf}
.blue-background{background:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background:#fa00fa}
.gray{color:#606060}
.gray-background{background:#7d7d7d}
.green{color:#006000}
.green-background{background:#007d00}
.lime{color:#00bf00}
.lime-background{background:#00fa00}
.maroon{color:#600000}
.maroon-background{background:#7d0000}
.navy{color:#000060}
.navy-background{background:#00007d}
.olive{color:#606000}
.olive-background{background:#7d7d00}
.purple{color:#600060}
.purple-background{background:#7d007d}
.red{color:#bf0000}
.red-background{background:#fa0000}
.silver{color:#909090}
.silver-background{background:#bcbcbc}
.teal{color:#006060}
.teal-background{background:#007d7d}
.white{color:#bfbfbf}
.white-background{background:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]{border-bottom:1px dotted}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#header,#content,#footnotes,#footer{max-width:none}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
</head>
<body class="book">
<div id="header">
<h1>SDP Legacy Upgrade Guide (for Unix)</h1>
<div class="details">
<span id="author" class="author">Perforce Professional Services</span><br>
<span id="email" class="email"><a href="mailto:consulting@perforce.com">consulting@perforce.com</a></span><br>
<span id="revnumber">version v2024.1,</span>
<span id="revdate">2024-07-16</span>
</div>
<div id="toc" class="toc">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#_preface">Preface</a></li>
<li><a href="#_overview">1. Overview</a>
<ul class="sectlevel2">
<li><a href="#_upgrade_order_sdp_first_then_helix_p4d">1.1. Upgrade Order: SDP first, then Helix P4D</a></li>
<li><a href="#_upgrading_helix_p4d_and_other_software">1.2. Upgrading Helix P4D and Other Software</a></li>
<li><a href="#_sdp_and_p4d_version_compatibility">1.3. SDP and P4D Version Compatibility</a></li>
<li><a href="#_sdp_upgrade_methods">1.4. SDP Upgrade Methods</a></li>
</ul>
</li>
<li><a href="#_upgrade_planning_in_place_upgrades">2. Upgrade Planning - In-Place Upgrades</a>
<ul class="sectlevel2">
<li><a href="#_plan_what_is_being_upgraded">2.1. Plan What Is Being Upgraded</a></li>
<li><a href="#_upgrade_duration">2.2. Upgrade Duration</a></li>
<li><a href="#_sdp_machines_and_instances">2.3. SDP Machines and Instances</a></li>
<li><a href="#_mount_point_names">2.4. Mount Point Names</a></li>
<li><a href="#_sdp_structure">2.5. SDP Structure</a>
<ul class="sectlevel3">
<li><a href="#_sdp_pre_2019_1_structure">2.5.1. SDP Pre-2019.1 Structure</a></li>
<li><a href="#_sdp_2019_1_structure">2.5.2. SDP 2019.1+ Structure</a></li>
</ul>
</li>
<li><a href="#_topology_option_shared_archives">2.6. Topology Option: Shared Archives</a></li>
<li><a href="#_p4home_dir_or_symlink">2.7. P4HOME: Dir or Symlink</a></li>
<li><a href="#_instance_bin_dir_or_symlink">2.8. Instance Bin: Dir or Symlink</a></li>
<li><a href="#_operating_system_user_osuser">2.9. Operating System User (OSUSER)</a></li>
<li><a href="#_home_directory_for_osuser">2.10. Home Directory for OSUSER</a></li>
<li><a href="#_metadata_symlink_type">2.11. Metadata Symlink Type</a></li>
<li><a href="#_init_mechanism_systemd_or_sysv">2.12. Init Mechanism: Systemd or SysV</a></li>
<li><a href="#_depot_spec_map_fields">2.13. Depot Spec Map Fields</a>
<ul class="sectlevel3">
<li><a href="#_multiple_depot_storage_volumes">2.13.1. Multiple Depot Storage Volumes</a></li>
</ul>
</li>
<li><a href="#_serverid_definition_and_replica_setup">2.14. ServerID Definition and Replica Setup</a></li>
</ul>
</li>
<li><a href="#_upgrade_procedure_in_place_upgrades">3. Upgrade Procedure - In-Place Upgrades</a>
<ul class="sectlevel2">
<li><a href="#_preparation">3.1. Preparation</a>
<ul class="sectlevel3">
<li><a href="#_plan_communications">3.1.1. Plan Communications</a></li>
<li><a href="#_plan_system_backups">3.1.2. Plan System Backups</a></li>
<li><a href="#_run_verify_sdp_sh">3.1.3. Run verify_sdp.sh</a></li>
<li><a href="#_plan_user_lockout">3.1.4. Plan User Lockout</a></li>
<li><a href="#_acquire_downloads">3.1.5. Acquire Downloads</a></li>
<li><a href="#_extract_new_sdp_directory">3.1.6. Extract new <code>sdp</code> Directory</a></li>
<li><a href="#_generate_new_sdp_shell_environment_files">3.1.7. Generate new SDP Shell Environment Files</a>
<ul class="sectlevel4">
<li><a href="#_the_p4_vars_file">3.1.7.1. The p4_vars File</a></li>
<li><a href="#_instance_vars_files">3.1.7.2. Instance Vars Files</a></li>
</ul>
</li>
<li><a href="#_plan_password_file_location_changes">3.1.8. Plan Password File Location Changes</a></li>
<li><a href="#_account_for_typical_customization">3.1.9. Account for Typical Customization</a></li>
<li><a href="#_account_for_sdp_additions">3.1.10. Account for SDP Additions</a></li>
<li><a href="#_deeper_customizations">3.1.11. Deeper Customizations</a></li>
<li><a href="#_instance_p4review_scripts">3.1.12. Instance P4Review Scripts</a></li>
<li><a href="#_broker_config_files">3.1.13. Broker Config Files</a></li>
<li><a href="#_generate_new_sdp_instance_bin_files">3.1.14. Generate New SDP Instance Bin Files</a></li>
<li><a href="#_check_for_systemd_service_files">3.1.15. Check for systemd service files</a></li>
<li><a href="#_plan_changes_to_configurables">3.1.16. Plan Changes to Configurables</a></li>
</ul>
</li>
<li><a href="#_execution">3.2. Execution</a>
<ul class="sectlevel3">
<li><a href="#_lockout_users">3.2.1. Lockout Users</a></li>
<li><a href="#_disable_crontabs">3.2.2. Disable Crontabs</a></li>
<li><a href="#_stop_services">3.2.3. Stop Services</a>
<ul class="sectlevel4">
<li><a href="#_stop_services_with_systemd">3.2.3.1. Stop Services with Systemd</a></li>
<li><a href="#_stop_services_with_sysv">3.2.3.2. Stop Services with SysV</a></li>
</ul>
</li>
<li><a href="#_backup_the_current_sdp_common_dir">3.2.4. Backup the current SDP Common Dir</a></li>
<li><a href="#_upgrade_physical_structure">3.2.5. Upgrade Physical Structure</a>
<ul class="sectlevel4">
<li><a href="#_replace_instance_symlink_with_directory">3.2.5.1. Replace Instance Symlink with Directory</a></li>
<li><a href="#_convert_fixed_to_variable_metadata_symlinks">3.2.5.2. Convert Fixed to Variable Metadata Symlinks</a></li>
<li><a href="#_replace_instance_symlink_with_directory_2">3.2.5.3. Replace Instance Symlink with Directory</a></li>
</ul>
</li>
<li><a href="#_put_new_sdp_in_place">3.2.6. Put New SDP in place</a></li>
<li><a href="#_deploy_new_sdp_common_files">3.2.7. Deploy new SDP Common Files</a></li>
<li><a href="#_put_new_sdp_init_scripts_in_place">3.2.8. Put New SDP Init scripts In Place</a></li>
<li><a href="#_put_new_p4_vars_in_place">3.2.9. Put New p4_vars In Place</a></li>
<li><a href="#_put_new_instance_vars_in_place">3.2.10. Put New Instance Vars In Place</a></li>
<li><a href="#_put_new_p4review_files_in_place">3.2.11. Put New P4Review Files In Place</a></li>
<li><a href="#_copy_and_relocate_password_files">3.2.12. Copy and Relocate Password Files</a></li>
<li><a href="#_upgrade_systemd_service_files">3.2.13. Upgrade systemd service files</a></li>
<li><a href="#_upgrade_sysv_etcinit_d">3.2.14. Upgrade SysV /etc/init.d</a></li>
<li><a href="#_start_services">3.2.15. Start Services</a>
<ul class="sectlevel4">
<li><a href="#_start_services_with_systemd">3.2.15.1. Start Services with Systemd</a></li>
<li><a href="#_start_services_with_sysv">3.2.15.2. Start Services with SysV</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#_set_sdp_counters">3.3. Set SDP Counters</a></li>
<li><a href="#_update_depot_specs">3.4. Update Depot Specs</a></li>
<li><a href="#_execute_planned_configuration_changes">3.5. Execute Planned Configuration Changes</a></li>
<li><a href="#_re_enable_crontabs">3.6. Re-Enable Crontabs</a></li>
<li><a href="#_open_the_flood_gates">3.7. Open The Flood Gates</a></li>
<li><a href="#_post_operation_steps">3.8. Post Operation Steps</a>
<ul class="sectlevel3">
<li><a href="#_cleanup">3.8.1. Cleanup</a></li>
</ul>
</li>
<li><a href="#_custom_hms_managed_installations">Appendix A: Custom HMS Managed Installations</a></li>
<li><a href="#_dfm_brokers_for_legacy_upgrade">Appendix B: DFM Brokers for Legacy Upgrade</a></li>
<li><a href="#_upgrading_from_an_earlier_patch_of_sdp_2020_1">Appendix C: Upgrading from an earlier patch of SDP 2020.1</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="_preface">Preface</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This document provides an overview of the process to upgrade the Perforce Helix Server Deployment Package (SDP) from any older version (dating back to 2007) to the SDP 2020.1 release, also referred to as "r20.1".</p>
</div>
<div class="paragraph">
<p>If your SDP version is 2020.1 or newer, refer to the <a href="SDP_Guide.Unix.html">SDP Guide (Unix)</a> for instructions on how to upgrade from SDP 2020.1 to any later version. Starting from SDP 2020.1, the upgrade procedure for the SDP is aided by an automated and incremental upgrade mechanism similar to p4d itself, capable of upgrade SDP from the current release to any future version so long as the current release is SDP 2020.1 or newer.</p>
</div>
<div class="paragraph">
<p>This document describes the process of upgrading to SDP 2020.1.</p>
</div>
<div class="paragraph">
<p><strong>Please Give Us Feedback</strong></p>
</div>
<div class="paragraph">
<p>Perforce welcomes feedback from our users. Please send any suggestions for improving this document or the SDP to <a href="mailto:consulting@perforce.com">consulting@perforce.com</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_overview">1. Overview</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The Perforce Server Deployment Package (SDP) software package, just like the Helix Core software it manages, evolves over time and requires occasional upgrades to remain supported. Further, patches may be released over time.</p>
</div>
<div class="paragraph">
<p>This document discusses how to upgrade the SDP, and when in relationship to Helix Core itself.</p>
</div>
<div class="sect2">
<h3 id="_upgrade_order_sdp_first_then_helix_p4d">1.1. Upgrade Order: SDP first, then Helix P4D</h3>
<div class="paragraph">
<p>The SDP should be upgraded prior to the upgrade of Helix Core (P4D). If you are planning to upgrade P4D to or beyond P4D 2019.1 from a prior version of P4D, you <em>must</em> upgrade the SDP first. If you run multiple instances of P4D on a given machine (potentially each running different versions of P4D), upgrade the SDP first before upgrading any of the instances.</p>
</div>
<div class="paragraph">
<p>The SDP should also be upgraded before upgrading other Helix software on machines using the SDP, including P4D, P4P, P4Broker, and the 'p4' command line client on the server machine. Even if not strictly required, upgrading the SDP first is <strong>strongly</strong> recommended, as SDP keeps pace with changes in the p4d upgrade process, and can ensure a smooth upgrade.</p>
</div>
</div>
<div class="sect2">
<h3 id="_upgrading_helix_p4d_and_other_software">1.2. Upgrading Helix P4D and Other Software</h3>
<div class="paragraph">
<p>See the <a href="SDP_Guide.Unix.html">SDP Guide (Unix)</a> for instructions on how to upgrade Helix binaries in the SDP structure after the SDP has been upgraded to 2020.1 or later.</p>
</div>
</div>
<div class="sect2">
<h3 id="_sdp_and_p4d_version_compatibility">1.3. SDP and P4D Version Compatibility</h3>
<div class="paragraph">
<p>The SDP is often forward- and backward-compatible with P4D versions. However, for best results they should be kept in sync by upgrading SDP before P4D. This is partly because the SDP contains logic to upgrade P4D, which can change as P4D evolves.</p>
</div>
<div class="paragraph">
<p>The SDP is aware of the P4D version(s) it manages, and has backward-compatibility logic to support older versions of P4D. This is guaranteed for supported versions of P4D. Backward compatibility of SDP with older versions of P4D may extend farther back then officially supported versions, though without the "officially supported" guarantee.</p>
</div>
</div>
<div class="sect2">
<h3 id="_sdp_upgrade_methods">1.4. SDP Upgrade Methods</h3>
<div class="paragraph">
<p>There are several methods for upgrading to a new version of the SDP:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>In-Place, Manual Upgrades</strong>: Manual upgrades of the SDP must be performed to upgrade from versions older than 2020.1 in-place on existing machines. This document provides details on how to do this.</p>
</li>
<li>
<p><strong>In-Place, Automated Upgrades</strong>: Automation assisted in-place upgrades can be done if your current SDP version is 2020.1 or later. and you are upgrading to 2021.1 and later. Refer to documentation in <a href="SDP_Guide.Unix.html">SDP Guide (Unix)</a> for upgrading <em>from</em> SDP 2020.1 onward.</p>
</li>
<li>
<p><strong>Migration-Style Upgrades</strong>: A migration-style upgrade is one in which the existing server machines (virtual or physical) are left in place, and brand new "green field" machines are installed fresh using the <a href="https://swarm.workshop.perforce.com/projects/perforce_software-helix-installer">Helix Installer</a> (which installs the latest SDP on a "green field" baseline machine with only the operating system installed). Then the Helix Core data is migrated from the existing hardware to the new hardware. This approach is especially appealing when upgrading other aspects of the infrastructure at the same time as the SDP, such as the hardware and/or operating system. Migration style upgrades require new hardware, and provide a straightforward rollback option because the original hardware is left in place.</p>
</li>
<li>
<p><strong>Custom with HMS</strong>: The <a href="https://swarm.workshop.perforce.com/projects/perforce_software-hms">Helix Management System</a> is used by some customers. See <a href="#_custom_hms_managed_installations">Appendix 3.A, <em>Custom HMS Managed Installations</em></a></p>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_upgrade_planning_in_place_upgrades">2. Upgrade Planning - In-Place Upgrades</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Legacy SDP upgrades require some familiarization that should be done prior to scheduling an upgrade.</p>
</div>
<div class="paragraph">
<p>The following information is useful for planning SDP in-place upgrades.</p>
</div>
<div class="sect2">
<h3 id="_plan_what_is_being_upgraded">2.1. Plan What Is Being Upgraded</h3>
<div class="paragraph">
<p>Presumably if you are reading this, you are intending to upgrade the SDP. During planning, you’ll want to decide if you want to upgrade only the SDP. Or you may want to upgrade Helix Core software in the same maintenance window.</p>
</div>
<div class="paragraph">
<p>Tactically, the SDP upgrade is done first. However, upgrading SDP and Helix Core can be done in the same maintenance window, so both upgrade tasks can be done in one upgrade session. Alternately, Helix Core can be upgraded at a later date after the SDP upgrade.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Decide whether Helix Core will be upgraded during the same work session that SDP is upgraded.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_upgrade_duration">2.2. Upgrade Duration</h3>
<div class="paragraph">
<p>Key questions to answer during upgrade planning are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Will p4d need to be taken offline?</p>
</li>
<li>
<p>If so, how long?</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Most upgrades to SDP to 2020.1 will require downtime for the Helix Core (p4d) server, even if p4d is not being upgraded. The only exception to requiring downtime is if the current SDP is r2019.<em>x</em> <strong>and</strong> your SDP is <em>not</em> configured to use <code>systemd</code>, i.e. does not have <code>/etc/systemd/system/p4*.service</code> files. (Most 2019-2021 era SDP deployments use systemd, so this is a narrow exception.)</p>
</div>
<div class="paragraph">
<p>If the current SDP <strong>and</strong> P4D versions are both r2019.1 or later, the downtime can be brief. The scripts can be upgraded while the server is live, stopping p4d only long enough to change the <code>systemd *.service</code> files with new ones.</p>
</div>
<div class="paragraph">
<p>If your SDP is older than 2019.1, other changes will be needed depending on your SDP version, which will extend the downtime for p4d needed to upgrade the SDP. Read on to get a sense for what steps are required, which vary based on your SDP version.</p>
</div>
<div class="paragraph">
<p>If you are upgrading P4D along with the SDP, and your P4D version is older than 2019.1, live checkpoints are recommended after the upgrade is complete. This can significantly extend downtime required. The "to-or-thru P4D 2019.1" upgrades involve significant Helix Core database structural changes. If your Helix topology includes edge servers, you’ll want to account for taking checkpoints of the edge servers in "to-or-thru 2019.1" upgrade planning; edge checkpoints can occur in parallel with the checkpoint on the master server to reduce overall upgrade process duration.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="title">Drivers of Downtime Duration</div>
<div class="paragraph">
<p>The big drivers of required downtime duration are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Is SDP 2019.1+? If so, no SDP structural changes are needed, so less downtime is needed.</p>
</li>
<li>
<p>Is P4D being upgraded to-or-thru 2019.1? If yes, significantly longer downtime is needed, both for the p4d upgrade process and taking a live checkpoint after.</p>
</li>
<li>
<p>Time required to execute the SDP upgrade steps that you’ll define in detail with information from later in this document. The older the SDP version, the more steps required.</p>
</li>
<li>
<p>Sophisticated global topologies with many machines take longer for these one-time legacy upgrades, due to needing to run commands on multiple machines.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Note that, once on the SDP 2020.1+ and using P4D 2019.1+, we do not expect any future upgrades to require extended downtime. Upgrade simplification and downtime reduction are priorities for both Helix Core and the SDP.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_sdp_machines_and_instances">2.3. SDP Machines and Instances</h3>
<div class="paragraph">
<p>Early in your planning, you’ll want to take stock of all server machines on which the SDP is to be upgraded.</p>
</div>
<div class="paragraph">
<p>For each machine, you’ll need to be aware of what SDP instances need to be upgraded on that machine.</p>
</div>
<div class="paragraph">
<p>For each instance on any given machine, determine what servers or services are in place. For example, a given machine might be a master p4d server for one instance, a replica for another, and a simple proxy for a third instance.</p>
</div>
</div>
<div class="sect2">
<h3 id="_mount_point_names">2.4. Mount Point Names</h3>
<div class="paragraph">
<p>You will need to be aware of the three standard SDP mount points. While referred to as "mount points" in this document, in any given installation, any or all of the three SDP mount points may be simple directories on the root storage volume, or symlinks to some other storage volume. In some installations, fewer than three volumes were used, and in some cases 4 were used (2 for metadata). In some cases the operating system root volume was used as one of the volumes. Investigate and be aware of how your installation was configured. Comparing the output of <code>pwd</code> and <code>pwd -P</code> in the same directory can be informative.</p>
</div>
<div class="paragraph">
<p>The mount points do not necessarily need to be changed during the SDP upgrade process, as the SDP structural design has always and remains flexible with respect to mount point names. However, understanding whether the "mount points" are actual mount points, regular directories or symlinks is something to be aware of for detailed planning.</p>
</div>
<div class="paragraph">
<p>In the examples below, the modern SDP mount point names are used:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>/hxdepots</code> - Volume for versioned files and rotated/numbered metadata journals.</p>
</li>
<li>
<p><code>/hxmetadata</code>- Volume for active and offline metadata. In some cases the single <code>/hxmetadata</code> is replaced with the pair <code>/hxmetadata1</code> and <code>/hxmetadata2</code>.</p>
</li>
<li>
<p><code>/hxlogs</code> - Volume for active journal and various logs.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Depending on the version of the SDP, the above values may be used, or earlier defaults such as:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>/depotdata</code> for <code>/hxdepots</code></p>
</li>
<li>
<p><code>/metadata</code> for <code>/hxmetadata</code></p>
</li>
<li>
<p><code>/logs</code> for <code>/hxlogs</code>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>In some cases, custom values were used like <code>/p4depots</code>, <code>/p4db</code>, <code>/p4jnl</code>, etc. In these cases, it is important to know what standard names are referred to by the local names.</p>
</div>
<div class="paragraph">
<p>In the sample steps in this document, adapt the steps to use your local values for mount point names to the new values.</p>
</div>
<div class="paragraph">
<p>If your site uses two volumes for metadata, <code>/hxmetadata1</code> and <code>/hxmetadata2</code>, continue using those same names.</p>
</div>
</div>
<div class="sect2">
<h3 id="_sdp_structure">2.5. SDP Structure</h3>
<div class="paragraph">
<p>If your SDP is 2019.1 or newer, skip this section.</p>
</div>
<div class="paragraph">
<p>Become familiar with the Pre-SDP 2019.1 and SDP 2019.1+ structures. (Note: This is not related to the P4D version).</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Determine if SDP structural changes are needed.
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="_sdp_pre_2019_1_structure">2.5.1. SDP Pre-2019.1 Structure</h4>
<div class="paragraph">
<p>Before SDP 2019.1:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>/p4</code> is a directory on the operating system root volume, <code>/</code>.</p>
</li>
<li>
<p><code>/p4/<em>N</em></code> is a symlink to a directory is typically the mount point for a storage volume (<code>/hxdepots</code> by default).</p>
</li>
<li>
<p><code>/p4/<em>N</em></code> contains symlinks for <code>/hxdepots</code>, <code>/hxmetadata</code>, and <code>hxlogs</code>, as well as tickets and trust files.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_sdp_2019_1_structure">2.5.2. SDP 2019.1+ Structure</h4>
<div class="paragraph">
<p>In SDP 2019.1+:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>/p4</code> is a directory on the operating system root volume, <code>/</code>, (same as Pre-2019.1 Structure).</p>
</li>
<li>
<p><code>/p4/<em>N</em></code> is local directory on the operating system root volume,</p>
</li>
<li>
<p><code>/p4/<em>N</em></code> contains symlinks for <code>/hxdepots</code>, <code>/hxmetadata</code>, and <code>hxlogs</code>, as well as tickets and trust files (same as the Pre-2019.1 structure)</p>
</li>
<li>
<p><code>/p4/<em>N</em>/bin</code> is local directory on the operating system root volume. The <code>bin</code> directory is the only actual directory in <code>/p4/<em>N</em></code>; other items are files or symlinks to directories.</p>
</li>
</ul>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The <code>verify_sdp.sh</code> script (included in the SDP starting with SDP 2019.1) gives errors if the 2019.1+ SDP structure is not in place.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Converting the SDP structure in-place to the new style requires downtime on the edge/replica of interest.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_topology_option_shared_archives">2.6. Topology Option: Shared Archives</h3>
<div class="paragraph">
<p>A topology option with SDP deployments is to share the <code>/hxdepots</code> mount point across machines, e.g. with NFS. SDP upgrade procedures involve updating the <code>/p4/common</code> directory that is physically on the <code>/hxdepots</code> volume. When updating the <code>/p4/common</code> on one machine, be aware that any changes will be immediately visible on all other machines that share from the same NFS network location.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
Be aware of any shared <code>/hxdepots</code> volumes when planning SDP upgrades.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_p4home_dir_or_symlink">2.7. P4HOME: Dir or Symlink</h3>
<div class="paragraph">
<p>If your SDP is 2019.1 or newer, skip this section.</p>
</div>
<div class="paragraph">
<p>In current and all legacy SDP installations, including all topology variations, the top-level <code>/p4</code> directory is always a regular directory on the local machine. However, the instance directory, e.g. the <code>1</code> in <code>/p4/1/root</code>, might be a directory or a symlink depending on your SDP version.</p>
</div>
<div class="paragraph">
<p>In the modern SDP, the <code>/p4/<em>N</em></code> directory (where <code><em>N</em></code> is the SDP instance, e.g. <code>1</code>), is also a regular directory on the local machine. This <code>/p4/<em>N</em></code> directory is referred to as the <code>P4HOME</code> directory for the instance.</p>
</div>
<div class="paragraph">
<p>In older versions of the SDP, the <code><em>N</em></code> was a symlink rather than a local directory. Check with a command like <code>ls -l /p4/<em>N</em></code> to determine if the P4HOME dir is a symlink or a directory. If it is a symlink, the upgrade procedure will need to change the symlink to a directory.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
If the <code><em>N</em></code> in <code>/p4/<em>N</em></code> is a symlink rather than a directory, you’ll need to change that to a directory in the upgrade procedure.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_instance_bin_dir_or_symlink">2.8. Instance Bin: Dir or Symlink</h3>
<div class="paragraph">
<p>If your SDP is 2019.1 or newer, skip this section.</p>
</div>
<div class="paragraph">
<p>In the modern SDP, the "Instance bin" directory, <code>/p4/<em>N</em>/bin</code>, is a directory. As with P4HOME, on older versions of the SDP, <code>/p4/<em>N</em>/bin</code> may be a directory or symlink. Check with a command like <code>ls -l /p4/<em>N</em>/bin</code> to determine if that is a directory or symlink, depending on how old the SDP is.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
If the <code>bin</code> in <code>/p4/<em>N</em>/bin</code> is a symlink rather than a directory, you’ll need to change that to a directory in the upgrade procedure.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_operating_system_user_osuser">2.9. Operating System User (OSUSER)</h3>
<div class="paragraph">
<p>You will need to be aware of your operating system user (OSUSER) that <code>p4d</code> runs as in your environment.</p>
</div>
<div class="paragraph">
<p>The sample upgrade steps below assume that Perforce runs as the <code>perforce</code> operating system user, which is typical. You do not need to change it, but you will need to adapt the samples below if your OSUSER is something other than <code>perforce</code>.</p>
</div>
<div class="paragraph">
<p>The OUSER user should dedicated to operating the Perforce Helix Core and related Helix services.</p>
</div>
</div>
<div class="sect2">
<h3 id="_home_directory_for_osuser">2.10. Home Directory for OSUSER</h3>
<div class="paragraph">
<p>In modern installations, the default home directory is <code>/home/perforce</code>, though in some older installations the home directory is <code>/p4</code>. In either case, this does not need to be changed during the upgrade process.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
As a general guideline, we recommend using a local home directory for the account under which p4d runs, as opposed to an auto-mounted home directory. Using an auto-mounted home directory can be a source of operational instability. While changing to a local directory is not a hard requirement, it is recommended.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_metadata_symlink_type">2.11. Metadata Symlink Type</h3>
<div class="paragraph">
<p>Depending on how old the SDP in place is, the structure will have either <em>Fixed</em> or <em>Variable</em> Metadata Symlinks. Determine which you have.</p>
</div>
<div class="paragraph">
<p>To determine this, login as the OSUSER (e.g. <code>perforce</code>), and run a command like this sample (for instance <code>1</code>):</p>
</div>
<div class="literalblock">
<div class="content">
<pre>ls -l /p4/1/root /p4/1/offline_db</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>root</code> and <code>offline_db</code> will be always symlinks in all versions of the SDP. However, they might be fixed or variable.</p>
</div>
<div class="paragraph">
<p><strong>Variable Metadata Symlink References</strong></p>
</div>
<div class="paragraph">
<p>If one of the symlinks points to a directory ending in <code>db1</code>, and the other in <code>db2</code> (it doesn’t matter which is pointing to which), you have <strong>variable metadata symlinks</strong>.</p>
</div>
<div class="paragraph">
<p><strong>Fixed Metadata Symlink References</strong></p>
</div>
<div class="paragraph">
<p>If the target of the <code>root</code> and <code>offline_db</code> symlinks points to directories ending in the same names, i.e. <code>root</code> and <code>offline_db</code>, then you have <strong>fixed metadata symlinks.</strong></p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
If you have <strong>fixed metadata symlinks</strong>, your upgrade procedure will need to convert them to <strong>variable metadata symlinks</strong>, per examples below.
</td>
</tr>
</table>
</div>
</div>
<div class="sect2">
<h3 id="_init_mechanism_systemd_or_sysv">2.12. Init Mechanism: Systemd or SysV</h3>
<div class="paragraph">
<p>You will need to determine whether you are running with the Systemd or SysV init mechanism.</p>
</div>
<div class="paragraph">
<p>Generally, newer operating systems like RHEL/CentOS 7 & 8, Ubuntu 18.04 and 20.04, and SuSE 12 & 15 will run with the <code>systemd</code> init mechanism. Older ones likely use the SysV init scripts (with some exceptions). If the command <code>systemctl</code> exists in your path, then you are running a system that supports systemd.</p>
</div>
</div>
<div class="sect2">
<h3 id="_depot_spec_map_fields">2.13. Depot Spec Map Fields</h3>
<div class="paragraph">
<p>During planning, for each SDP instance, determine if depot spec <code>Map:</code> fields are used, and if the triggers table references the script <code>SetDefaultDepotSpecMapField.py</code>.</p>
</div>
<div class="paragraph">
<p>The modern SDP uses the <code>server.depot.root</code> configurable to define where depots are stored. In older versions of the SDP, the <code>Map:</code> field of the depot spec was used to track which depots were stored physically on which volumes. Starting in 2014, <code>p4d</code> introduced the <code>server.depot.root</code> configurable to define a standard location for all depots. The SDP took advantage of this, and stopped using the depot spec <code>Map:</code> fields. The <code>Map:</code> field was managed manually, or with the add of the (now obsolete) <code>SetDefaultDepotSpecMapField.py</code>.</p>
</div>
<div class="paragraph">
<p>For each instance, use the <code>p4 depots</code> command, and examine the <code>Map:</code> field of each depot spec to see if it has the default value or not. The default value is the name of the depot followed by a trailing <code>/…​</code>. If any <code>Map:</code> fields have values other than the default, we want to be aware of that during planning, as we’ll need to deal with them during the upgrade.</p>
</div>
<div class="paragraph">
<p>Following is a way to perform the analysis quickly:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># Get a list of depots.
p4 -ztag -F %type%:%name%:%map% depots > /tmp/d1.txt</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre># Trim depot types that don't apply for this check.
grep -Ev '^(remote|graph):' /tmp/d1.txt > /tmp/d2.txt
cut -d ':' -f 2,3 /tmp/d2.txt > /tmp/d3.txt</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre># This next long single-line command does the check.
while read -r dm; do d=${dm%%:*}; m=${dm##*:}; echo D=[$d] M=[$m]; [[ "${d}/..." == "$m" ]] || echo NONDEFAULT_MAP for depot $d; done < /tmp/d3.txt</pre>
</div>
</div>
<div class="paragraph">
<p>If the text <code>NONDEFAULT_MAP</code> appears in the output, there are depots with non-default <code>Map:</code> fields that need to be addressed.</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="title">Why not use depot spec <code>Map:</code> fields?</div>
<div class="paragraph">
<p>Using the <code>Map:</code> field of the depot spec had operational complexities, as it could not be easily seen unless the <code>p4d</code> process was online, which often it would not be during maintenance when depot moves occurred. Using symlinks to track what depots are on what physical volumes is simpler, always accessible, and allows for per-machine variations that are sometimes needed.</p>
</div>
</div>
</div>
<div class="paragraph">
<p>Use the <code>p4 triggers -o</code> command and see if your triggers table contains a reference to the <code>SetDefaultDepotSpecMapField.py</code>. If so, plan to remove that trigger during the upgrade.</p>
</div>
<div class="sect3">
<h4 id="_multiple_depot_storage_volumes">2.13.1. Multiple Depot Storage Volumes</h4>
<div class="paragraph">
<p>The SDP uses the <code>server.depot.root</code> configurable to define where depots are stored. <strong>All</strong> depots must <strong>appear</strong> to p4d as being in <code>/p4/<em>N</em>/depots</code>, which is the <code>server.depot.root</code> value. In cases where depots are physically be stored on multiple storage volumes, symlinks in the <code>/p4/<em>N</em>/depots</code> directory reference the actual storage location.</p>
</div>
<div class="paragraph">
<p>For example, say for instance <code>1</code> you use <code>/hxdepots</code>, <code>/hxdepots2</code> and <code>/hxdepots3</code> volumes. The <code>/p4/N/depots</code> symlink will point only to <code>/hxdepots/p4/N/depots</code>. This "primary storage volume," i.e. the one pointed to by the <code>depots</code> symlink, contains a mix of depot directories (for depots physically stored on that <code>/hxdepots</code> volume) and symlinks for each depot stored on the other volumes. Running an <code>ls</code> might look like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ ls -l /hxdepots/p4/1/depots/
total 0
drwxrwxr-x 4 perforce staff 128 Feb 16 2012 HR
drwxrwxr-x 8 perforce staff 256 Feb 16 2012 depot
drwxrwxr-x 5 perforce staff 160 Feb 16 2012 gwt
lrwxr-x--x 1 perforce staff 34 Feb 28 10:29 gwt-streams -> /hxdepots3/p4/1/depots/gwt-streams
drwxrwxr-x 4 perforce staff 128 Feb 16 2012 jam
drwxrwxr-x 7 perforce staff 224 Feb 16 2012 pb
drwxr-x--x 13 perforce staff 416 Feb 4 12:55 spec
lrwxr-x--x 1 perforce staff 29 Feb 28 10:29 system -> /hxdepots2/p4/1/depots/system</pre>
</div>
</div>
<div class="paragraph">
<p>During planning, determine if you need to add symlinks in your primary depot storage volume. These symlinks can safely be added immediately, though <code>p4d</code> will not use them until the <code>Map:</code> field of the server spec is cleared during the upgrade.</p>
</div>
<div class="paragraph">
<p>Once you have determined which instances require clearing of depot spec <code>Map:</code> fields and/or removal of the <code>SetDefaultDepotSpecMapField.py</code> trigger, plan to run the <code>clear_depot_Map_fields.sh</code> script for those instance during the upgrade processing.</p>
</div>
<div class="paragraph">
<p>For info on this script:</p>
</div>
<div class="listingblock">
<div class="title">Usage</div>
<div class="content">
<pre class="highlight"><code>USAGE for clear_depot_Map_fields.sh v1.2.0:
clear_depot_Map_fields.sh [-i <instance>] [-L <log>] [-v<n>] [-p|-n] [-D]
or
clear_depot_Map_fields.sh [-h|-man|-V]
DESCRIPTION:
This script obsoletes the SetDefaultDepotSpecMapField.py trigger.
It does so by following a series of steps. First, it ensures that
the configurable server.depot.root is set correctly, setting it
if it is not already set.
Next, the Triggers table is checked to ensure the call to the
SetDefaultDepotSpecMapField.py is not called; it is deleted from
the Triggers table if found.
Last, it resets the 'Map:' field of depot specs for depot
types where that is appropriate, setting it to the default value of
'<DepotName>/...', so that it honors the server.depot.root
configurable. This is done for depots of these types:
* stream
* local
* spec
* unload
* graph
but not these:
* archive
* remote
If an unknown depot type is encountered, the 'Map:' field is reset
as well if it is set.
This script does a preflight check first, reporting any cases
where the starting conditions are not as expected. These conditions
are treated as Errors, and will abort processing:
* Depot Map field set to something other than the default.
* Configurable server.depot.root is set, but to something other
than what it should be.
The following are treated as Warnings, and will be reported but
will not prevent processing.
* Configurable server.depot.root is already set.
* SetDefaultDepotSpecMapField.py not found in triggers.
* Depot already has 'Map:' field set to the default value:
<DepotName>/...
OPTIONS:
-v<n> Set verbosity 1-5 (-v1 = quiet, -v5 = highest).
-L <log>
Specify the path to a log file, or the special value 'off' to disable
logging. By default, all output (stdout and stderr) goes to
EDITME_DEFAULT_LOG
NOTE: This script is self-logging. That is, output displayed on the screen
is simultaneously captured in the log file. Do not run this script with
redirection operators like '> log' or '2>&1', and do not use 'tee.'
-p Run preflight checks only, and then stop. By default, actual changes
occur if preflight checks find no issues.
-n No-Op. No actions are taken that would affect data significantly;
instead commands are displayed rather than executed.
-D Set extreme debugging verbosity.
HELP OPTIONS:
-h Display short help message
-man Display man-style help message
-V Display version info for this script and its libraries.
EXAMPLES:
A typical flow for this script is to do a preflight first, and then
a live run, for any given instance:
clear_depot_Map_fields.sh -i 1 -p
clear_depot_Map_fields.sh -i 1
Note that if using '-n', the '-v5' flag should also be used.</code></pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_serverid_definition_and_replica_setup">2.14. ServerID Definition and Replica Setup</h3>
<div class="paragraph">
<p>Modern SDP uses and requires <code>server.id</code> files in the \$P4ROOT directory. If your SDP does not have <code>server.id</code> files in the \$P4ROOT directory, you’ll need to add them before starting p4d after upgrading.</p>
</div>
<div class="paragraph">
<p>When upgrading the SDP, you may want to redo replica, replacing any existing replicas with new ones generated with the SPD <code>mkrep.sh</code> script, and ensuring the ServerID values follow the SDP Server Spec Naming Standard and replication best practices. See the <a href="SDP_Guide.Unix.html">SDP Guide (Unix)</a> to learn about using <code>mkrep.sh</code>.</p>
</div>
<div class="paragraph">
<p>If you do plan to do this, you may want to plan your overall upgrade procedure as follows:</p>
</div>
<div class="olist arabic">
<ol class="arabic">
<li>
<p>Upgrade SDP (as detailed in this document).</p>
</li>
<li>
<p>Upgrade Helix Core to the latest version.</p>
</li>
<li>
<p>Redo Replication (if not already using SDP best practices).</p>
</li>
</ol>
</div>
<div class="paragraph">
<p>Tackling the replication redo increases the benefit of the overall upgrade. However, if checkpoints take a long time in your environment, it also may significantly increase the required duration of the downtime in the maintenance window. This is due to the need for new checkpoints as needed during the replication recreation process. It is possible to defer replication upgrades to a separate maintenance operation.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_upgrade_procedure_in_place_upgrades">3. Upgrade Procedure - In-Place Upgrades</h2>
<div class="sectionbody">
<div class="paragraph">
<p>With the familiarization and planning from the last section complete, move on to defining an upgrade procedure for your topology.</p>
</div>
<div class="paragraph">
<p>The procedure is broken into 3 phases:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Preparation</strong>: Preparation steps can be done in a non-disruptive manner on a production server ahead of the Execution, possibly days or more ahead of the target date for the actual upgrade.</p>
</li>
<li>
<p><strong>Execution</strong>: Execution steps are generally performed in a scheduled maintenance window.</p>
</li>
<li>
<p><strong>PostOp</strong>: PostOp steps are done some time after the upgrade is complete, perhaps days or weeks later. For example, some cleanup is done in PostOp. Often the upgrade procedure leaves copies of various files and directories around to support a fast abort of the upgrade. Such files are comforting to have around during the upgrade procedure, but after a time become clutter and should be removed.</p>
</li>
</ul>
</div>
<div class="sect2">
<h3 id="_preparation">3.1. Preparation</h3>
<div class="paragraph">
<p>Preparation steps are detailed below.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
These procedure involves deploying new files on the Production server ahead of the actual upgrade. As prescribed, the steps avoid interaction with a live running p4d server and with the SDP script operations of the current SDP. The preparation steps can be safely done without affecting behavior until you are ready to execute the upgrade. However, human error is always a possibility when working on a production server. Respect the machine, and type carefully!
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="_plan_communications">3.1.1. Plan Communications</h4>
<div class="paragraph">
<p>Crafting emails can be time consuming! Communications to end users should be prepared so that they are ready to send quickly during maintenance.</p>
</div>
<div class="paragraph">
<p>For the most part, this type of "back end system" upgrade is transparent to end users other than the associated downtime. However, if you have power users granted direct SSH access to the server machines, such users should also be made aware of SDP changes.</p>
</div>
</div>
<div class="sect3">
<h4 id="_plan_system_backups">3.1.2. Plan System Backups</h4>
<div class="paragraph">
<p>If your environment has special backup capabilities, such as snapshots of key storage volumes and/or the entire machine, it should be determined whether such things are to be utilized during this upgrade (generally before anything starts).</p>
</div>
</div>
<div class="sect3">
<h4 id="_run_verify_sdp_sh">3.1.3. Run verify_sdp.sh</h4>
<div class="paragraph">
<p>If you SDP is 2019.1 or newer, it will have the <code>verify_sdp.sh</code> script. Run it during preparation to ensure you have a good start state. Resolve issues detected by the script.</p>
</div>
</div>
<div class="sect3">
<h4 id="_plan_user_lockout">3.1.4. Plan User Lockout</h4>
<div class="paragraph">
<p>There are a variety of strategies for locking out users during maintenance. Choose what combination to apply in your environment.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>Protections table</strong>: Create a near-empty "maintenance mode" Protections table that references only the P4USER used by the SDP (typically <code>perforce</code>) and any replication service users (<code>svc_*</code>). As maintenance starts, save the standard Protections table, and put the maintenance one in place. At the end of maintenance, bring the original one back in place. (Be aware of whether your site has any polices or custom automation that might interfere with this method.)</p>
</li>
<li>
<p><strong>Temp Firewall Changes</strong>: Using network and/or host firewall rules can block end users out during maintenance. Be wary not to block replicas. (Warning: This can be complex and hard to get right, and may involve coordination with other teams if the Perforce admin does not have direct control over such things. Choose this option with care.)</p>
</li>
<li>
<p><strong>Temp P4PORT Change</strong>: In some environments, the P4PORT and P4BROKERPORT configured in the Instance Vars files are changed to non-production values not known to users during maintenance, and switched back when done. If there are replicas, there is a need to do <code>p4d -cset</code> commands to change replica’s P4TARGET back and forth between production and maintenance mode values.</p>
</li>
<li>
<p><strong>DFM Brokers</strong>: Down For Maintenance "(DFM)" brokers can be used for some types of upgrade. DFM brokers cannot be used if SDP structure change are needed, as all processes must be down in that case. The legacy upgrade procedure outlined in this document does not account for using DFM brokers, and for this particular upgrade we do not recommend using them. However, it is possible; see <a href="#_dfm_brokers_for_legacy_upgrade">Appendix 3.B, <em>DFM Brokers for Legacy Upgrade</em></a>.</p>
</li>
</ul>
</div>
</div>
<div class="sect3">
<h4 id="_acquire_downloads">3.1.5. Acquire Downloads</h4>
<div class="paragraph">
<p>Download the latest SDP tarball using <code>curl</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>curl -L -O https://swarm.workshop.perforce.com/projects/perforce_software-hms</pre>
</div>
</div>
<div class="paragraph">
<p>Copy the downloaded tarball to the machine and put it in <code>/hxdepots/sdp.Unix.tgz</code>. (If a file with the same name exists from a previous upgrade, move it aside first.)</p>
</div>
</div>
<div class="sect3">
<h4 id="_extract_new_sdp_directory">3.1.6. Extract new <code>sdp</code> Directory</h4>
<div class="literalblock">
<div class="content">
<pre>mkdir /hxdepots/new
cd /hxdepots/new
tar -xzf /hxdepots/sdp.Unix.tgz
cat /hxdepots/new/sdp/Version</pre>
</div>
</div>
<div class="paragraph">
<p>Verify that the contents of the <code>Version</code> file are as expected.</p>
</div>
<div class="paragraph">
<p>The <code>/hxdepots/new</code> folder structure is not referenced by the SDP, and thus a new SDP can be safely staged there ahead of the execution of the SDP upgrade.</p>
</div>
</div>
<div class="sect3">
<h4 id="_generate_new_sdp_shell_environment_files">3.1.7. Generate new SDP Shell Environment Files</h4>
<div class="paragraph">
<p>The following SDP shell environment files are generated and should be reviewed, comparing new files generated with a <code>*.new</code> extension with the corresponding files in the existing installation (without the <code>.new</code> suffix). Be careful not to modify the production files; only update the *.new files.</p>
</div>
<div class="paragraph">
<p>The Shell Environment Files to generate for review are:</p>
</div>
<div class="sect4">
<h5 id="_the_p4_vars_file">3.1.7.1. The p4_vars File</h5>
<div class="paragraph">
<p>The single <code>p4_vars</code> file is the main SDP shell environment file. Generate the new form of the file like this example, operated as the <code>perforce</code> OSUSER:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /p4/common/bin</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre># This long one-line command does a sed and redirects to a file.
sed -e "s:REPL_OSUSER:$USER:g" -e "s:REPL_SDPVERSION:$(cat /hxdepots/new/sdp/Version):g" /hxdepots/new/sdp/Server/Unix/p4/common/config/p4_vars.template > p4_vars.new</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre># Preserve the current KEEP* settings.
grep -E 'export KEEP.*=' p4_vars >> p4_vars.new</pre>
</div>
</div>
<div class="paragraph">
<p>The old file will contain <code>KEEP*</code> settings, possibly with custom values that should be preserved. That <code>grep</code> command above handles preservation of the <code>KEEP*</code> settings.</p>
</div>
</div>
<div class="sect4">
<h5 id="_instance_vars_files">3.1.7.2. Instance Vars Files</h5>
<div class="paragraph">
<p>The <code>/p4/common/config</code> directory in the SDP contains <code>p4_N.vars</code> shell environment files, one per SDP instance (e.g. <code>p4_1.vars</code>, <code>p4_abc.vars</code>, etc.).</p>
</div>
<div class="sidebarblock">
<div class="content">
<div class="title">What if there is no <code>/p4/common/config</code> ?</div>
<div class="paragraph">
<p>If the existing SDP does not have a <code>/p4/common/config</code> directory at all, as will be the case for very old versions of SDP, you can safely create the <code>config</code> directory during preparation.</p>
</div>
<div class="paragraph">
<p>In that case, leave off the <code>*.new</code> extension for files to be generated in <code>/p4/common/config, i.e. the `p4_N.vars</code> files (one per instance) and optional <code>p4_N.p4review.cfg</code> files created in that directory. Create the <code>/p4/common/config</code> directory by copying from the new SDP area, like so:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>su - perforce
cp -pr /hxdepots/new/sdp/Server/Unix/p4/common/config /p4/common/.</pre>
</div>
</div>
</div>
</div>
<div class="paragraph">
<p>In the following example, replace <code>1 abc</code> with your actual list of SDP instance names, delimited by spaces. Note that if you have many machines in your topology, it is possible that each machine may have a different set of instances. You’ll need to be aware of which instances are active on which machines. On any given machine with a given set of instances, do something like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>su - perforce
cd /p4/common/config
for i in 1 abc; do cp /hxdepots/new/sdp/Server/Unix/p4/common/config/instance_vars.template p4_${i}.vars.new; done</pre>
</div>
</div>
<div class="paragraph">
<p>The format of <code>p4_N.vars</code> files has evolved over time, so it is important to generate new files from the new template. For each p4_N.vars.new file, search for the string <code>REPL_</code> in the file to find strings that need to be replaced (everywhere except in comment blocks). Settings to be replaced are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>MAILTO</p>
</li>
<li>
<p>MAILFROM</p>
</li>
<li>
<p>P4USER</p>
</li>
<li>
<p>P4MASTER_ID</p>
</li>
<li>
<p>SSL_PREFIX</p>
</li>
<li>
<p>P4PORTNUM</p>
</li>
<li>
<p>P4BROKERPORTNUM</p>
</li>
<li>
<p>P4MASTERHOST (appears in some older versions as P4MASTER)</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>As needed, refer to the original <code>p4_N.vars</code> files to retrieve values. Following is the complete list of settings to check and see if you have values defined in your original Instance Vars file that may differ from the new template:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>MAILTO</p>
</li>
<li>
<p>MAILFROM</p>
</li>
<li>
<p>P4USER</p>
</li>
<li>
<p>P4MASTER_ID</p>
</li>
<li>
<p>SSL_PREFIX</p>
</li>
<li>
<p>P4PORTNUM</p>
</li>
<li>
<p>P4BROKERPORTNUM</p>
</li>
<li>
<p>P4MASTERHOST</p>
</li>
<li>
<p>PROXY_TARGET</p>
</li>
<li>
<p>PROXY_PORT</p>
</li>
<li>
<p>P4DTG_CFG</p>
</li>
<li>
<p>SNAPSHOT_SCRIPT</p>
</li>
<li>
<p>SDP_ALWAYS_LOGIN</p>
</li>
<li>
<p>SDP_AUTOMATION_USERS</p>
</li>
<li>
<p>The 'umask' setting, which is set with a command like <code>umask 0026</code>.</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_plan_password_file_location_changes">3.1.8. Plan Password File Location Changes</h4>
<div class="paragraph">
<p>In the modern SDP, passwords are stored in files like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>/p4/common/config/.p4passwd.p4_1.admin
/p4/common/config/.p4passwd.p4_abc.admin</pre>
</div>
</div>
<div class="paragraph">
<p>where <code>1</code> and <code>abc</code> are sample instance names. If you have such files, no changes for passwords are needed during the upgrade procedure. In very old versions of the SDP, the password for the super user (defined by the P4USER setting in the shell environment files) was defined in the single file:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>/p4/common/bin/adminpass</pre>
</div>
</div>
<div class="paragraph">
<p>If you have the old password file <code>/p4/common/bin/adminpass</code>, plan to copy from the legacy location to the new home in <code>/p4/common/config</code> it during the upgrade procedure. If you have more than one instance, you will need to copy the <code>adminpass</code> file to multiple <code>/p4/common/config/.p4passwd.p4_N.admin</code> files.</p>
</div>
</div>
<div class="sect3">
<h4 id="_account_for_typical_customization">3.1.9. Account for Typical Customization</h4>
<div class="paragraph">
<p>If the SDP has been customized in your environment, custom upgrade procedures may be required. An understanding of what was customized and why will be useful in determining if custom upgrade procedures are required.</p>
</div>
<div class="paragraph">
<p>In typical deployments, the SDP is not customized, or only customized in some way that is no longer needed due to improvements in the "stock" SDP.</p>
</div>
<div class="paragraph">
<p>Starting with the SDP 2020.1 release, there is a new mechanism to cleanly separate typical configuration changes from customizations. The SDP <code>p4_vars</code> file and Instance Vars files may contain local custom modifications made by administrators or Perforce Consultants. When generating new Instance Vars files, be sure to review old Instance Vars files for any custom code or logic.</p>
</div>
<div class="paragraph">
<p>The <code>p4_vars</code> files and generated Instance Vars files (e.g. <code>p4_1.vars</code>) each have a line at the bottom of the generated portion of the file that looks like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>### MAKE LOCAL CHANGES HERE:</pre>
</div>
</div>
<div class="paragraph">
<p>If any custom functionality is to be preserved, be sure to add it <strong><em>only</em></strong> after that line containing <code><mark>#</mark> MAKE LOCAL CHANGES HERE:</code></p>
</div>
<div class="paragraph">
<p>Future automated SDP upgrades will preserve any lines below the <code><mark>#</mark> MAKE LOCAL CHANGES HERE:</code> line. In addition to preserving content below that line, the right-side of all variable assignments anywhere in the file will be preserved extracted from existing Instance Vars files as well as <code>p4_vars</code>. For example, say if you have:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>export MAILLIST=MyAdminList@MyCompany.com</pre>
</div>
</div>
<div class="paragraph">
<p>That variable assignment will be preserved in future SDP upgrades.</p>
</div>
<div class="paragraph">
<p>Use this information when reviewing your <code>p4_vars.new</code> and <code>p4_1.vars.new</code> (or other Instance Vars files) in preparation for the upgrade.</p>
</div>
</div>
<div class="sect3">
<h4 id="_account_for_sdp_additions">3.1.10. Account for SDP Additions</h4>
<div class="paragraph">
<p>In many cases, customers have added custom trigger scripts into the SDP structure. Triggers are typically added in <code>/p4/common/bin/triggers</code> and possibly with instance-specific triggers in <code>/p4/<em>N</em>/bin/triggers</code>. Generally, custom triggers should not need to be changed, and can remain in place during the SDP upgrade.</p>
</div>
<div class="paragraph">
<p>However, custom triggers should be reviewed to determine if they depend on any custom environment variables that may have been added to the SDP shell environment files (the <code>p4_vars</code> file and/or Instance Vars) to support the custom triggers. Consider custom triggers in <a href="#_account_for_typical_customization">Section 3.1.9, “Account for Typical Customization”</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_deeper_customizations">3.1.11. Deeper Customizations</h4>
<div class="paragraph">
<p>If you need help determining if and how the SDP was customized in your environment, <a href="mailto:consulting@perforce.com">Perforce Consulting</a> may be of assistance. Note that customizations are not supported by Perforce Support.</p>
</div>
</div>
<div class="sect3">
<h4 id="_instance_p4review_scripts">3.1.12. Instance P4Review Scripts</h4>
<div class="paragraph">
<p>The legacy p4review "review daemon" scripts are still supported in the SDP, but have become obsolete with Helix Swarm offering the needed functionality. Determine if you still need them. If not, skip to the next section.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
If Helix Swarm is used, use Swarm’s <code>honor_p4_reviews</code> feature to displace the legacy <code>p4review</code> scripts and config files. Swarm has its own "project-based" email notification scheme, which can be augmented with <code>honor_p4_reviews</code> to also provide notifications based on the <code>Reviews:</code> field of the user spec.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>If you need them, generate *.new config files as per this example. In the following example, replace <code>1 abc</code> with your actual list of SDP instance names for which review daemons are active. Review daemons are only enabled on the master server machine for an instance.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>su - perforce
cd /p4/common/config
for i in 1 abc; do cp /hxdepots/new/sdp/Server/Unix/p4/common/config/p4review.cfg.template p4_${i}.p4review.cfg.new; done</pre>
</div>
</div>
<div class="paragraph">
<p>Review the generated *.new config file and search for any settings whose values (the the right of the <code>=</code> sign) start with <code>REPL_</code>. Replace any such settings with appropriate values using your original file as a guide.</p>
</div>
<div class="paragraph">
<p>It is possible the new files, after configuration, may not have changed from the older ones if your SDP version is recent enough.</p>
</div>
</div>
<div class="sect3">
<h4 id="_broker_config_files">3.1.13. Broker Config Files</h4>
<div class="paragraph">
<p>Broker config files, <code>p4_N.broker.cfg</code>, may also exist in <code>/p4/common/config</code>. These are not affected by the SDP upgrade procedure, and can be ignored.</p>
</div>
<div class="paragraph">
<p>In some older SDP deployments, broker config files were deployed to other locations such as <code>/p4/<em>N</em>/bin</code>. Any broker config files outside of <code>/p4/common/config</code> must be moved there and named per the naming convention for broker configuration files. For more information, see: <a href="https://swarm.workshop.perforce.com/projects/perforce-software-sdp/view/main/doc/SDP_Guide.Unix.html#_configuring_systemd_p4broker_multiple_configs" class="bare">https://swarm.workshop.perforce.com/projects/perforce-software-sdp/view/main/doc/SDP_Guide.Unix.html#_configuring_systemd_p4broker_multiple_configs</a></p>
</div>
</div>
<div class="sect3">
<h4 id="_generate_new_sdp_instance_bin_files">3.1.14. Generate New SDP Instance Bin Files</h4>
<div class="paragraph">
<p>If the current SDP is 2018.1 or newer, skip this section.</p>
</div>
<div class="paragraph">
<p>Examine the <code>p4d_N_init</code> script in the 'instance bin' folder, <code>/p4/<em>N</em>/bin</code>.</p>
</div>
<div class="paragraph">
<p>Does the actual code look like this sample (with comments and the "shebang" <code>#!/bin/bash</code> line removed)?</p>
</div>
<div class="literalblock">
<div class="content">
<pre>export SDP_INSTANCE=N
/p4/common/bin/p4d_base $SDP_INSTANCE $@</pre>
</div>
</div>
<div class="paragraph">
<p>If the <code>p4d_N_init</code> script already looks like this, then the 'instance bin' folder does not need to be touched during the upgrade process. Skip the rest of this section.</p>
</div>
<div class="paragraph">
<p>If, however, the *_init script has more code, then all the <code>p4*_init</code> scripts will need to be replaced during the upgrade execution. Templates are available in <code>/p4/common/etc/init.d</code>. The templates contains a few values that will need to be replaced.</p>
</div>
<div class="paragraph">
<p>Identify existing <code>p4*_init</code> scripts to be replaced, and create new files with a <code>*.new</code> suffix. For example, for instance <code>1</code>, generate new p4d and p4broker init scripts like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /p4/1/bin</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre># This long command line generates p4d_1_init.new.
sed -e s:REPL_SDP_INSTANCE:1:g /hxdepots/new/sdp/Server/Unix/p4/common/etc/init.d/p4d_instance_init.template > p4d_1_init.new</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>chmod +x p4d_1_init.new</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre># This long command line generates p4broker_1_init.new.
sed -e s:REPL_SDP_INSTANCE:1:g /hxdepots/new/sdp/Server/Unix/p4/common/etc/init.d/p4broker_instance_init.template > p4broker_1_init.new</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>chmod +x p4d_1_init.new</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_check_for_systemd_service_files">3.1.15. Check for systemd service files</h4>
<div class="paragraph">
<p>The format of Systemd service files (sometimes referred to as 'Unit' files) changed with the SDP 2020.1 release. As part of planning, it is helpful to identify if systemd is already in use, and which Perforce Helix services are managed with systemd.</p>
</div>
<div class="paragraph">
<p>If the <code>/etc/systemd/system</code> directory exists, then the Systemd init mechanism is available. On systems that use the Systemd init mechanism, we recommend using it. You can check that with an <code>ls</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>ls -ld /etc/systemd/system</pre>
</div>
</div>
<div class="paragraph">
<p>Once systemd is configured for any given service, SDP 2020.1 <strong>requires</strong> using the systemd mechanism (i.e. the <code>systemctl</code> command) to start/stop Perforce Helix services (for data safety and consistency of management). Depending on your SDP version and how it was installed, there may or may not already be <code>p4*.service</code> files.</p>
</div>
<div class="paragraph">
<p>You can get a list of such services with:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>ls -lrt /etc/systemd/system/p4*.service</pre>
</div>
</div>
<div class="paragraph">
<p>In any case, in the Execution phase below, new systemd <code>p4*.service</code> files will be put in place, which may be new, or may replace existing <code>p4*.service</code> files.</p>
</div>
</div>
<div class="sect3">
<h4 id="_plan_changes_to_configurables">3.1.16. Plan Changes to Configurables</h4>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
This step is optional, and requires basic familiarity with bash scripting.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Modern SDP versions contain a script named <code>configure_new_server.sh</code> that makes various configuration changes to a server. That script captures best practices for a "green field" fresh new server installation.</p>
</div>
<div class="paragraph">
<p>This implements best practices in various ways:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Creates <code>spec</code> and <code>unload</code> depots.</p>
</li>
<li>
<p>Runs several <code>p4 configure set</code> commands to define configurable values.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>The <code>configure_new_server.sh</code> script should <strong>not</strong> be executed for existing instances as is, because it is intended only for "green field" installs. However, it can be used as a reference. Start by making a copy of it, an in your own version review what it does. Make case-by-case decisions on what configurables you want, what values you want, and whether you want it to create <code>spec</code> and <code>unload</code> depots. If you already have such depots, remove the logic block that creates the new depots. Be sure to understand each line of the script, and ensure the logic and values set fit your environment.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Expect this to be a painstaking process. Only set configurables that you are comfortable with.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>This documentation may prove helpful: <a href="https://www.perforce.com/manuals/cmdref/Content/CmdRef/configurables.configurables.html" class="bare">https://www.perforce.com/manuals/cmdref/Content/CmdRef/configurables.configurables.html</a>. Also, you can contact <a href="mailto:support-helix-core@perforce.com">Perforce Support</a> for information on specific configurables.</p>
</div>
<div class="paragraph">
<p>The script should be crafted during upgrade preparation, which may require some research. It should be executed when specified in the Execution phase.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /hxdepots/new/sdp/Server/setup
cp configure_new_server.sh configure_THIS_server.sh
chmod +wx configure_THIS_server.sh</pre>
</div>
</div>
<div class="paragraph">
<p>Then modify your local <code>configure_THIS_server.sh</code> script as desired. Typically the workflow for modifying the script involves running <code>p4 configure show</code> commands for any configurable the script would set with a <code>p4 configure set</code> command, and using the <code>p4 configure show</code> output to current values for settings with value the script would set.</p>
</div>
<div class="paragraph">
<p>If you need help determining evaluating your script, <a href="mailto:consulting@perforce.com">Perforce Consulting</a> may be of assistance. While this part of the upgrade is optional, some of the configurables can result in significant performance and functional benefits.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_execution">3.2. Execution</h3>
<div class="paragraph">
<p>This section outlines sample steps for executing an actual upgrade after planning and preparations identified in <a href="#_preparation">Section 3.1, “Preparation”</a> have been completed. The following typically performed in a scheduled maintenance window.</p>
</div>
<div class="paragraph">
<p>Execution steps detailed below.</p>
</div>
<div class="sect3">
<h4 id="_lockout_users">3.2.1. Lockout Users</h4>
<div class="paragraph">
<p>Execute whatever steps was planned in <a href="#_plan_user_lockout">Section 3.1.4, “Plan User Lockout”</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_disable_crontabs">3.2.2. Disable Crontabs</h4>
<div class="paragraph">
<p>Capture original crontabs on all servers, and then disable the active crontab. On each machine as <code>perforce</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>crontab -l</pre>
</div>
</div>
<div class="paragraph">
<p>If the <code>crontab -l</code> command reports <code>no crontab for perforce</code>, you can skip remaining steps on that machine. Typically SDP machines will have something in crontab, so this is likely an issue you may want to fix before or during the upgrade procedure. If you decide no crontab is needed on a given machine, be aware of that for the execution in <a href="#_re_enable_crontabs">Section 3.6, “Re-Enable Crontabs”</a>. If that <code>crontab -l</code> command does generate output, continue as <code>perforce</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[[ -d /p4/common/etc/cron.d ]] || mkdir -p /p4/common/etc/cron.d
cd /p4/common/etc/cron.d</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>crontab -l > crontab.$USER.$(hostname -s).old.DELETE_ME_LATER</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre># This next long command adjusts the crontab.
sed 's:daily_backup.sh:daily_checkpoint.sh:g' crontab.$USER.$(hostname -s).old.DELETE_ME_LATER | grep -Ev 'recreate_db_' > crontab.$USER.$(hostname -s)</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>crontab -r</pre>
</div>
</div>
<div class="paragraph">
<p>You should then review the crontab.$USER.$(hostname -s) file. The long command above with the <code>sed</code> and <code>grep -v</code> is safe to run in that it will generate a functionally correct crontab file. However, it might result in a file that has comments mismatched with deleted text. That can be cleaned up with manual review.</p>
</div>
</div>
<div class="sect3">
<h4 id="_stop_services">3.2.3. Stop Services</h4>
<div class="paragraph">
<p>Stop the <code>p4d</code> service for all instances on this machine. Also stop all p4broker services running on this machine (if any).</p>
</div>
<div class="paragraph">
<p>For this SDP maintenance, the broker cannot be left running (e.g. to broadcast a "Down For Maintenance (DFM)" message) because the structure change cannot be started until <em>all</em> processes launched from the SDP directory structure have stopped.</p>
</div>
<div class="sect4">
<h5 id="_stop_services_with_systemd">3.2.3.1. Stop Services with Systemd</h5>
<div class="paragraph">
<p>Sample systemd commands to stop the services, executed as <code>perforce</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>sudo systemctl status p4d_1 p4broker_1
sudo systemctl stop p4d_1 p4broker_1
sudo systemctl status p4d_1 p4broker_1</pre>
</div>
</div>
<div class="paragraph">
<p>The extra <code>status</code> commands before and after the start/stop commands are for situational awareness. These are not strictly necessary.</p>
</div>
</div>
<div class="sect4">
<h5 id="_stop_services_with_sysv">3.2.3.2. Stop Services with SysV</h5>
<div class="paragraph">
<p>Sample SysV commands to stop the services, executed as <code>perforce</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>p4d_1_init status
p4d_1_init stop
p4d_1_init status</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>p4broker_1_init status
p4broker_1_init stop
p4broker_1_init status</pre>
</div>
</div>
<div class="paragraph">
<p>The extra <code>status</code> commands before and after the start/stop commands are for situational awareness. These are not strictly necessary.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_backup_the_current_sdp_common_dir">3.2.4. Backup the current SDP Common Dir</h4>
<div class="paragraph">
<p>On each machine, copy the old SDP directory:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /hxdepots/p4
cp -pr common OLD.common.$(date +'%Y-%m-%d')</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_upgrade_physical_structure">3.2.5. Upgrade Physical Structure</h4>
<div class="paragraph">
<p>In this step, the physical structure of the upgrade is done for pre-2019.1 SDP. Skip this step if you are already on the 2019.1+ structure.</p>
</div>
<div class="paragraph">
<p>The structure of the SDP changed in the 2019.1 release, to increase performance and reduce complexity in post-failover operations. The following notes describe how to do an in-place conversion to the new structure.</p>
</div>
<div class="paragraph">
<p>Following is the procedure to upgrade the structure in-place on a machine.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
In the following sample procedure, the default SDP instance name of <code>1</code> is used, and default mount point names are used. Adapt this to your environment by applying this procedure to each instance on any given machine. If you have multiple instances, apply this procedure for each instance, one at a time.
</td>
</tr>
</table>
</div>
<div class="sect4">
<h5 id="_replace_instance_symlink_with_directory">3.2.5.1. Replace Instance Symlink with Directory</h5>
<div class="paragraph">
<p>Skip this step if you are already on the 2019.1+ structure.</p>
</div>
<div class="paragraph">
<p>Move the instance symlink aside, and replace it with a regular directory. Then copy the <code>.p4*</code> files (e.g. <code>.p4tickets</code> and <code>.p4trust</code>) into the new directory.
Sample commands:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /p4
mv 1 1.old_symlink.OLD_DELETE_ME_LATER
mkdir 1
cd 1
cp -p /p4/1.old_symlink.OLD_DELETE_ME_LATER/.p4t* .</pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_convert_fixed_to_variable_metadata_symlinks">3.2.5.2. Convert Fixed to Variable Metadata Symlinks</h5>
<div class="paragraph">
<p>Skip this step if you are already using Variable Metadata Symlinks.</p>
</div>
<div class="paragraph">
<p>If you have Fixed Metadata Symlinks, first convert them to to Variable Metadata Symlinks. If you already have Variable Metadata Symlinks, proceed to <a href="#_replace_instance_symlink_with_directory">Section 3.2.5.1, “Replace Instance Symlink with Directory”</a></p>
</div>
<div class="paragraph">
<p>In this step, move the underlying directories that will be pointed to by the <code>root</code> and <code>offline_db</code> symlink names, and move them to their <code>db1</code> and <code>db2</code> names.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>mv /hxmetadata/p4/1/root /hxmetadata/p4/1/db1
mv /hxmetadata/p4/1/offline_db /hxmetadata/p4/1/db2</pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="_replace_instance_symlink_with_directory_2">3.2.5.3. Replace Instance Symlink with Directory</h5>
<div class="paragraph">
<p>Recreate the same symlinks you see reported by the <code>ls</code> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>ls -l /p4/1.old_symlink.OLD_DELETE_ME_LATER/*
cd /p4/1</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>ln -s /hxmetadata/p4/1/db1 root
ln -s /hxmetadata/p4/1/db2 offline_db</pre>
</div>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Do not just copy the sample commands above. Pay close attention to the <code>ls</code> output, and make sure the <code>root</code> points to whatever it was pointing to before, either a directory ending in <code>db1</code> or <code>db2</code> (unless you just converted from Fixed Metadata Symlinks in STEP 4). Also confirm that <code>offline_db</code> and <code>root</code> aren’t both pointing to the same directory; one should be pointing to <code>db1</code> and the other to <code>db2</code>.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Then, create additional symlinks akin to whatever else is in <code>/p4/1.old_symlink.OLD_DELETE_ME_LATER</code></p>
</div>
<div class="paragraph">
<p>That should look something like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /p4/1
ln -s /hxdepots/p4/1/depots
ln -s /hxdepots/p4/1/checkpoints
ln -s /hxdepots/p4/1/checkpoints.YourEdgeServerID
ln -s /hxlogs/p4/1/logs
ln -s /hxlogs/p4/1/tmp</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>ls -l</pre>
</div>
</div>
<div class="paragraph">
<p>Next, create the <code>bin</code> directory, as a local directory and copy files to it:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>mkdir bin
cd bin
cp /p4/1.old_symlink.OLD_DELETE_ME_LATER/bin/p4d_1_init .
cp /p4/1.old_symlink.OLD_DELETE_ME_LATER/bin/p4broker_1_init .
ln -s /p4/common/bin/p4broker_1_bin p4broker_1
ln -s /p4/common/bin/p4_bin p4_1</pre>
</div>
</div>
<div class="paragraph">
<p>Last, take a look at <code>/p4/1.old_symlink.OLD_DELETE_ME_LATER/bin/p4d_1</code> - that <code>p4d_1</code> will be either a tiny script or a symlink (depending on whether your p4d is case sensitive or not). If you server is case sensitive, it will be a symlink. If your server is case-insensitive, it will be a tiny script.</p>
</div>
<div class="paragraph">
<p>If your server is case sensitive, create the symlink like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>ln -s /p4/common/bin/p4d_1_bin p4d_1</pre>
</div>
</div>
<div class="paragraph">
<p>OR, if your server is case-insensitive, that p4d_1 will be a tiny script, so just copy it:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cp /p4/1.old_symlink.OLD_DELETE_ME_LATER/bin/p4d_1 .</pre>
</div>
</div>
<div class="paragraph">
<p>Then, start your server again, and run the <code>verify_sdp.sh</code> script and confirm that it’s happy now.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_put_new_sdp_in_place">3.2.6. Put New SDP in place</h4>
<div class="paragraph">
<p>Put the new SDP in place:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /hxdepots
mv sdp sdp.$(date +'%Y-%m-%d').OLD_DELETE_ME_LATER
mv new/sdp .</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /p4
ln -f -s /hxdepots/sdp</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>/p4/sdp</code> symlink will now point to the new SDP, and <code>cat /p4/sdp/Version</code> will display the new SDP version. The <code>/p4/sdp</code> can be thought of as the full contents of the SDP tarball, while the <code>/p4/common</code>, <code>/p4/ssl</code>, and <code>/p4/<instance></code> structure are the live SDP files and scripts.</p>
</div>
</div>
<div class="sect3">
<h4 id="_deploy_new_sdp_common_files">3.2.7. Deploy new SDP Common Files</h4>
<div class="paragraph">
<p>The <code>rsync</code> command here will update files in the live <code>/p4/common</code> structure with the latest files from the SDP, overwriting changed SDP files. However, it will not update or remove any files that have been added under <code>/p4/common</code>, such as site-local triggers that may have been added in <code>/p4/common/bin/triggers</code>.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>rsync -a /p4/sdp/Server/Unix/p4/common/ /p4/common</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_put_new_sdp_init_scripts_in_place">3.2.8. Put New SDP Init scripts In Place</h4>
<div class="paragraph">
<p>If you generated new <code>p4*_init</code> scripts in preparation, put them in place now, doing something like this as <code>perforce</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /p4/1/bin
mv p4d_1_init p4d_1_init.OLD_DELETE_ME_LATER
mv p4d_1_init.new p4d_1_init</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>mv p4broker_1_init p4broker_1_init.OLD_DELETE_ME_LATER
mv p4broker_1_init.new p4broker_1_init</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_put_new_p4_vars_in_place">3.2.9. Put New p4_vars In Place</h4>
<div class="paragraph">
<p>Put the new p4_vars.new file in place doing something like this as <code>perforce</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /p4/common/bin
mv p4_vars p4_vars.OLD_DELETE_ME_LATER
mv p4_vars.new p4_vars</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_put_new_instance_vars_in_place">3.2.10. Put New Instance Vars In Place</h4>
<div class="paragraph">
<p>Put all the new Instance Vars files in place doing something like this as <code>perforce</code> and replacing <code>1 abc</code> with your list of instances:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /p4/common/config</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre># This single-line command moves old instance Vars files aside, and puts new ones in place:
for i in 1 abc; do mv p4_${i}.vars p4_${i}.vars.OLD_DELETE_ME_LATER; mv p4_${i}.vars.new p4_${i}.vars; done</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_put_new_p4review_files_in_place">3.2.11. Put New P4Review Files In Place</h4>
<div class="paragraph">
<p>If you generated new P4Review files put them in place, doing something like this as <code>perforce</code> and replacing <code>1 abc</code> with your list of instances:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /p4/common/config</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre># This single-line command moves old P4Review files aside and puts the new ones in place:
for i in 1 abc; do mv p4_${i}.p4review.cfg p4_${i}.p4review.cfg.OLD_DELETE_ME_LATER; mv p4_${i}.p4review.cfg.new p4_${i}.p4review.cfg; done</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_copy_and_relocate_password_files">3.2.12. Copy and Relocate Password Files</h4>
<div class="paragraph">
<p>If the need to copy password files was identified in <a href="#_plan_password_file_location_changes">Section 3.1.8, “Plan Password File Location Changes”</a>, do those copies now. Do something like this as <code>perforce</code> and replacing <code>1 abc</code> with your list of instances:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>for i in 1 abc; do cp -pf /p4/common/bin/adminpass /p4/common/config/.p4passwd.p4_${i}.admin; done</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>mv /p4/common/bin/adminpass /p4/common/bin/adminpass.DELETE_ME_LATER</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_upgrade_systemd_service_files">3.2.13. Upgrade systemd service files</h4>
<div class="paragraph">
<p>The format of systemd unit files changed with the SDP 2020.1 release. If systemd is not used, skip this section.</p>
</div>
<div class="paragraph">
<p>The SDP 2020.1 release includes templates for System unit files in <code>/p4/common/etc/systemd/system</code>. These should be deployed on each machine that uses SDP, and for each Helix service (e.g. <code>p4d</code>, <code>p4broker</code>, <code>p4p</code>) within each SDP instance.</p>
</div>
<div class="paragraph">
<p>For example, the following sample commands, which must be executed as <code>root</code>, will create or replace systemd <code>*.service</code> files for <code>p4d</code> and <code>p4broker</code> for SDP instance <code>1</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /etc/systemd/system</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>sed -e s:__INSTANCE__:1:g -e s:__OSUSER__:perforce:g /p4/common/etc/systemd/system/p4d_N.service.t > p4d_1.service</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>chmod 755 p4d_1.service</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>sed -e s:__INSTANCE__:1:g -e s:__OSUSER__:perforce:g /p4/common/etc/systemd/system/p4broker_N.service.t > p4broker_1.service</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>chmod 755 p4broker_1.service</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>systemctl daemon-reload</pre>
</div>
</div>
<div class="paragraph">
<p>Repeat the above procedure for each additional instance you have, replacing the <code>1</code> with the instance name. Be careful to make two substitutions on each <code>sed</code> command line. For example, if your instance is <code>abc</code>, replace <code>:1:</code> with something like <code>:abc:</code>, and replace <code>_1</code> with <code>_abc</code>.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
The new format of the systemd *.service files works only with the new SDP scripts in <code>/p4/common/bin</code>. The services will not start if the new scripts are deployed without the changes to the *.service files, or vice versa.
</td>
</tr>
</table>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
Do <strong>not</strong> make the <code>chmod</code> commands more restrictive; the <code>*.service</code> files must be world-readable (.e.g <code>755</code>).
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_upgrade_sysv_etcinit_d">3.2.14. Upgrade SysV /etc/init.d</h4>
<div class="paragraph">
<p>This step applies only to machines using the SysV init mechanism; see <a href="#_init_mechanism_systemd_or_sysv">Section 2.12, “Init Mechanism: Systemd or SysV”</a>.</p>
</div>
<div class="paragraph">
<p>In older versions of the SDP, there was sometimes a copy of the <code>/p4/N/bin/*_init</code> scripts in <code>/etc/init.d</code>. In modern SDP, these are replaced with symlinks. If they are already symlinks, no changes are needed.</p>
</div>
<div class="paragraph">
<p>The following sample commands, which must be executed as <code>root</code>, will create or replace init files for <code>p4d</code> and <code>p4broker</code> for SDP instance <code>1</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cd /etc/init.d
mv p4d_1_init p4d_1_init.old.DELETE_ME_LATER
mv p4broker_1_init p4broker_1_init.old.DELETE_ME_LATER
ln -s /p4/1/bin/p4d_1_init
ln -s /p4/1/bin/p4broker_1_init
chkconfig --del p4d_1_init
chkconfig --del p4broker_1_init
chkconfig --add p4d_1_init
chkconfig --add p4broker_1_init
chkconfig p4d_1_init on
chkconfig p4broker_1_init on</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>mv</code> and <code>chkconfig --del</code> commands will report errors if there are no existing files to move or configurations to delete. Such errors can be safely ignored, or those commands can be skipped if the referenced files don’t exist.</p>
</div>
</div>
<div class="sect3">
<h4 id="_start_services">3.2.15. Start Services</h4>
<div class="paragraph">
<p>Start the <code>p4d</code> service for all instances on this machine. Also start p4broker services running on this machine (if any).</p>
</div>
<div class="sect4">
<h5 id="_start_services_with_systemd">3.2.15.1. Start Services with Systemd</h5>
<div class="paragraph">
<p>Sample systemd commands to start the services, executed as <code>perforce</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>source p4_vars 1
sudo systemctl status p4d_1 p4broker_1
sudo systemctl start p4d_1 p4broker_1
sleep 3
sudo systemctl status p4d_1 p4broker_1
p4 info</pre>
</div>
</div>
<div class="paragraph">
<p>The extra <code>status</code> commands before and after the start/stop commands are for situational awareness. These are not strictly necessary.</p>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
The <code>systemctl start</code> command returns immediately after a request to the system mechanism has been made to start service. However, the return of the command should NOT be taken as an indication that the service is actually up; that must verified, e.g. with <code>p4 info</code>.
</td>
</tr>
</table>
</div>
<div class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
If you execute the second <code>systemctl status</code> command or the <code>p4 info</code> command too quickly after the <code>start</code> command, the service will not have started. Give it several seconds and try again.
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="_start_services_with_sysv">3.2.15.2. Start Services with SysV</h5>
<div class="paragraph">
<p>Sample SysV commands to start the services, executed as <code>perforce</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>p4d_1_init status
p4d_1_init start
p4d_1_init status</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>p4broker_1_init status
p4broker_1_init start
p4broker_1_init status</pre>
</div>
</div>
<div class="paragraph">
<p>The extra <code>status</code> commands before and after the start/stop commands are for situational awareness. These are not strictly necessary.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_set_sdp_counters">3.3. Set SDP Counters</h3>
<div class="paragraph">
<p>Set the SDP_VERSION and SDP_DATE counters.</p>
</div>
<div class="paragraph">
<p>The SDP_VERSION counter is the SDP version.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>p4 counter SDP_VERSION "$(cat /p4/sdp/Version)"
p4 counter SDP_DATE "$(date +'%Y-%m-%d')"</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_update_depot_specs">3.4. Update Depot Specs</h3>
<div class="paragraph">
<p>Based on the planning done in <a href="#_depot_spec_map_fields">Section 2.13, “Depot Spec Map Fields”</a>, instances should be identified that require clearing of depot spec <code>Map:</code> fields and/or removal of the <code>SetDefaultDepotSpecMapField.py</code> trigger. For each instance, run the script as in the following example, replacing <em>N</em> with your actual instance name(s):</p>
</div>
<div class="literalblock">
<div class="content">
<pre>/p4/sdp/Server/Unix/p4/common/sdp_upgrade/clear_depot_Map_fields.sh -i N</pre>
</div>
</div>
<div class="paragraph">
<p>If you have more than one instance, run the command for each instance, changing the <em>N</em> value for each instance.</p>
</div>
</div>
<div class="sect2">
<h3 id="_execute_planned_configuration_changes">3.5. Execute Planned Configuration Changes</h3>
<div class="paragraph">
<p>If changes to configuration changes were identified in <a href="#_plan_changes_to_configurables">Section 3.1.16, “Plan Changes to Configurables”</a> and a <code>configure_THIS_server.sh</code> script was crafted, execute it now as the perforce user:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>/p4/sdp/Server/setup/configure_THIS_server.sh</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_re_enable_crontabs">3.6. Re-Enable Crontabs</h3>
<div class="paragraph">
<p>Re-enable crontabs as <code>perforce</code> on each machine with commands like these:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>crontab -l
crontab /p4/common/etc/cron.d/crontab.$USER.$(hostname -s)
crontab -l</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>crontab -l</code> before and after is done for situational awareness and to confirm the crontab was loaded correctly.</p>
</div>
</div>
<div class="sect2">
<h3 id="_open_the_flood_gates">3.7. Open The Flood Gates</h3>
<div class="paragraph">
<p>At this point, do any sanity testing you desire to have confidence everything is OK.</p>
</div>
<div class="paragraph">
<p>Then, allow users back in by undoing whatever you did to lock users out in <a href="#_lockout_users">Section 3.2.1, “Lockout Users”</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="_post_operation_steps">3.8. Post Operation Steps</h3>
<div class="paragraph">
<p>Cleanup steps can occur after the upgrade. In some cases cleanup is done immediately following the upgrade; in other cases it may be deferred by days or weeks.</p>
</div>
<div class="sect3">
<h4 id="_cleanup">3.8.1. Cleanup</h4>
<div class="paragraph">
<p>Temporary files and directories with <code>.DELETE_ME_LATER</code> suffixes created during the upgrade procedure can now be deleted.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_custom_hms_managed_installations">Appendix A: Custom HMS Managed Installations</h3>
<div class="paragraph">
<p>If the Helix Management System (HMS) is used to manage this installation, you should have custom site-specific documentation for upgrading the SDP that supersedes this documentation. If the file <code>/p4/common/bin/hms</code> exists at your site, you have an HMS-managed site. Contact <a href="mailto:consulting@perforce.com">Perforce Consulting</a> for more information.</p>
</div>
<div class="paragraph">
<p>Note that HMS solutions are inherently custom and not officially supported, but can be fully automated for global Helix Core topologies.</p>
</div>
</div>
<div class="sect2">
<h3 id="_dfm_brokers_for_legacy_upgrade">Appendix B: DFM Brokers for Legacy Upgrade</h3>
<div class="paragraph">
<p>If you desire to use DFM brokers for the legacy upgrade to SDP 2020.1 as outlined in this document, you cannot use the standard init scripts and procedures for managing the p4broker process, as those scripts and procedures will be disrupted during the upgrade process. Also, using a DFM broker will tie up the port number, creating a bit of complexity and interfering with scripts or procedures that start/stop the services. Care must be taken to avoid attempting to run the DFM broker during certain parts of the upgrade process.</p>
</div>
<div class="paragraph">
<p>With those caveats noted, if care is taken, it is possible to use a specially configured DFM broker for the legacy upgrade to SDP 2020.1. It can be done by making a copy of the new <code>p4broker</code> binary to some non-SDP-managed location (such as <code>/home/perforce</code>) and generating a disposable configuration file.</p>
</div>
<div class="paragraph">
<p>Here is a sample procedure to use a DFM broker. You will need to modify the sample configuration file to use the correct ports for your environment.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>mkdir /home/perforce/dfm
cd /home/perforce/dfm
curl -s -O http://ftp.perforce.com/perforce/r23.1/bin.linux26x86_64/p4broker
chmod +x p4broker</pre>
</div>
</div>
<div class="paragraph">
<p>Here is a similar sample using a DFM broker on SSL:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>mkdir /home/perforce/dfm
cd /home/perforce/dfm
curl -s -O http://ftp.perforce.com/perforce/r23.1/bin.linux26x86_64/p4broker
chmod +x p4broker
chmod 700 /home/perforce/dfm
export P4SSLDIR=/home/perforce/dfm
./p4broker -Gc</pre>
</div>
</div>
<div class="paragraph">
<p>Then, create a broker config file <code>/home/perforce/dfm/p4broker.cfg</code> with contents like this sample:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code> target = ssl:1666;
listen = ssl:1667;
directory = /home/perforce/dfm;
logfile = p4broker.dfm.log;
admin-email = null;
admin-phone = null;
admin-name = null;
command: .*
{
action = reject;
message = "\nPerforce Helix is Down for scheduled maintenance\n";
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>The DFM broker can then be started with a simple command line like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>export P4SSLDIR=/home/perforce/dfm/p4broker
/home/perforce/dfm/p4broker -c /home/perforce/dfm/p4broker.cfg</pre>
</div>
</div>
<div class="paragraph">
<p>It can be stopped with a command like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>pkill -f /home/perforce/dfm/p4broker</pre>
</div>
</div>
<div class="paragraph">
<p>This stop command will stop only the DFM broker. (Note: The <code>-f</code> in that command is not "force", but rather "full regex matching"; see <code>man pgrep</code> for more information.)</p>
</div>
<div class="paragraph">
<p>In your planning, account for starting and stopping the DFM broker at times to avoid interfering with operations that start/stop services.</p>
</div>
<div class="paragraph">
<p>If you have multiple machines in your environment, copy the <code>/home/perforce/dfm</code> directory to all machines, and account for starting/stopping the DFM broker on all machines in your planning.</p>
</div>
</div>
<div class="sect2">
<h3 id="_upgrading_from_an_earlier_patch_of_sdp_2020_1">Appendix C: Upgrading from an earlier patch of SDP 2020.1</h3>
<div class="paragraph">
<p>If you are upgrading SDP from a prior patch of 2020.1, the procedure is the same as above, though most steps can be skipped (per details above). <strong>When upgrading from the 2020.1 GA release or any subsequent patch to the current latest patch, no Helix Core service downtime is required</strong>.</p>
</div>
<div class="paragraph">
<p>Note that customers upgrading from development DEV-PRE-RELEASE versions of SDP 2020.1 will require a small amount of downtime if the the systemd init mechanim is used, as the systemd *.services files will need to be updated.</p>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Version v2024.1<br>
Last updated 2024-07-16 09:51:42 -0400
</div>
</div>
</body>
</html> | # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #31 | 30531 | C. Thomas Tyler |
Merge down from main to dev with: p4 merge -b perforce_software-sdp-dev |
||
| #30 | 30385 | C. Thomas Tyler | Regnerated docs for release. | ||
| #29 | 30294 | C. Thomas Tyler | Updated docs for release. | ||
| #28 | 30095 | Mark Zinthefer | Fixing typo regarding case-sensitivity in SDP Legacy_Upgrade doc | ||
| #27 | 30000 | C. Thomas Tyler |
Refined Release Notes and top-level README.md file in preparation for coming 2023.2 release. Adjusted Makefile in doc directory to also generate top-level README.html from top-level README.md file so that the HTML file is reliably updated in the SDP release process. Updated :revnumber: and :revdate: docs in AsciiDoc files to indicate that the are still current. Avoiding regen of ReleaseNotes.pdf binary file since that will need at least one more update before shipping SDP 2023.2. |
||
| #26 | 29700 | C. Thomas Tyler |
Updated Version to release SDP 2023.1.29699. Re-generated docs. |
||
| #25 | 29611 | C. Thomas Tyler |
Updated Version to release SDP 2023.1.29610. Re-generated docs. |
||
| #24 | 29251 | C. Thomas Tyler |
Updated Version to release SDP 2022.2.29250. Re-generated docs. |
||
| #23 | 28988 | C. Thomas Tyler |
Updated Version to release SDP 2022.1.28987. Re-generated docs. |
||
| #22 | 28840 | C. Thomas Tyler |
Updated Version to release SDP 2022.1.28839. Re-generated docs. |
||
| #21 | 28411 | C. Thomas Tyler |
Updated Version to release SDP 2021.2.28410. Re-generated docs. |
||
| #20 | 28239 | C. Thomas Tyler |
Updated Version to release SDP 2021.1.28238. Re-generated docs. |
||
| #19 | 27920 | C. Thomas Tyler |
Updated Version to release SDP 2020.1.27919. Re-generated docs. |
||
| #18 | 27821 | C. Thomas Tyler |
Updated Version to release SDP 2020.1.27820. Re-generated docs. |
||
| #17 | 27763 | C. Thomas Tyler | Fix typo in SDP Legacy Upgrade Guide. | ||
| #16 | 27760 | C. Thomas Tyler |
Updated Version to release SDP 2020.1.27759. Re-generated docs. |
||
| #15 | 27725 | C. Thomas Tyler | Re-generated HTML and PDF from adoc files. | ||
| #14 | 27722 | C. Thomas Tyler |
Refinements to @27712: * Resolved one out-of-date file (verify_sdp.sh). * Added missing adoc file for which HTML file had a change (WorkflowEnforcementTriggers.adoc). * Updated revdate/revnumber in *.adoc files. * Additional content updates in Server/Unix/p4/common/etc/cron.d/ReadMe.md. * Bumped version numbers on scripts with Version= def'n. * Generated HTML, PDF, and doc/gen files: - Most HTML and all PDF are generated using Makefiles that call an AsciiDoc utility. - HTML for Perl scripts is generated with pod2html. - doc/gen/*.man.txt files are generated with .../tools/gen_script_man_pages.sh. #review-27712 |
||
| #13 | 27687 | C. Thomas Tyler |
SDP Legacy Upgrade Guide doc updates: * Customer feedback incorporated. THANK YOU! * Added new 'Upgrade systemd service files' section. * Cleaned up some incomplete text. * Fixed typo 'MAILLOST' -> 'MAILLIST'. * Added notes to crontab handling to deal with change from daily_backup.sh to daily_checkpoint.sh and removal of recreate_db_*.sh scripts. |
||
| #12 | 27686 | C. Thomas Tyler |
Updated SDP Legacy Upgrade Doc: * Retitled 'Broker Config Files - Nothing to do' to drop the 'Nothing to do', since broker config files need to be moved from /p4/N/bin for really old SDP installs. Added doc on what to do with them. * Fixed section numbering/indention level for sections 'Instance P4Review Scripts' and 'Broker Config Files'. |
||
| #11 | 27682 | C. Thomas Tyler |
Updated SDP Legacy Upgrade Doc: * Incorporated customer feedback and corrections. THANK YOU! |
||
| #10 | 27681 | C. Thomas Tyler |
Updated SDP Legacy Upgrade Doc: * Incorporated customer feedback and corrections. THANK YOU! * Added Appendix B on using DFM brokers during the legacy upgrade process. |
||
| #9 | 27677 | C. Thomas Tyler |
Updated SDP Legacy Upgrade Doc: * Incorporated customer feedback and corrections. THANK YOU! * Added section for moving password files from legacy location. * Added section for dealing with configurables. |
||
| #8 | 27676 | C. Thomas Tyler | Generated HTML only for legacy upgrade doc. | ||
| #7 | 27536 | C. Thomas Tyler |
Legacy Upgrade Guide doc updates: * Added 'Put New SDP in Place' section. * Added 'Set SDP Counters' section to set SDP_VERSION and SDP_DATE counters. * Covered updating depot spec Map fields. * Covered adding server.id files. * Added missing content on putting new SDP directory in place. SDP_Guide.Unix doc updates: * Added Legacy Upgrade Scripts section w/clear_depot_Map_fields.sh. Updated Makefile with new doc build dependencies. Regenerated docs. |
||
| #6 | 27526 | C. Thomas Tyler |
Updated Version to release SDP 2020.1.27524. Re-generated docs. |
||
| #5 | 27498 | C. Thomas Tyler | Legacy upgrade doc updates. | ||
| #4 | 27486 | C. Thomas Tyler | Doc updates, WIP. | ||
| #3 | 27322 | C. Thomas Tyler | Updated AsciiDoc-generated files. | ||
| #2 | 27253 | C. Thomas Tyler | Updated generated docs. | ||
| #1 | 27096 | C. Thomas Tyler |
Refactored SDP Legacy Upgrade content into a separate doc. The SDP Guide will be remain comprehensive and cover how to upgrade the SDP itself forwardm from the current version (2020.1) using the new, p4d-like incremental upgrade mechanism. The content for manual upgrade procedures needed to get older SDP installations to 2020.1 is only useful until sites are on 2020.1. This content is extensive, narrowly focused, and of value only once per installation, and thus the legacy upgrade content is separated into its own document. Regenerated work-in-progress HTML files for easier review. |