File: guide.html

package info (click to toggle)
cockpit 355-1
links: PTS, VCS
area: main
in suites: forky, sid
size: 311,568 kB
sloc: javascript: 774,787; python: 40,655; ansic: 35,157; cpp: 11,141; sh: 3,512; makefile: 580; xml: 261
file content (2628 lines) | stat: -rw-r--r-- 111,090 bytes
parent folder | download | duplicates (2)
<!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.26">
<title>Deployment Guide</title>
<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.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 pre>code{display:block}
.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>
</head>
<body id="guide" class="article toc2 toc-left">
<div id="header">
<h1>Deployment Guide</h1>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#cockpit-manual">Manual pages</a>
<ul class="sectlevel2">
<li><a href="#_cockpit1">cockpit(1)</a>
<ul class="sectlevel3">
<li><a href="#_name">Name</a></li>
<li><a href="#_description">Description</a></li>
<li><a href="#_components">Components</a></li>
<li><a href="#_bugs">Bugs</a></li>
<li><a href="#_author">Author</a></li>
<li><a href="#_see_also">See also</a></li>
</ul>
</li>
<li><a href="#_cockpit_conf5">cockpit.conf(5)</a>
<ul class="sectlevel3">
<li><a href="#_name_2">Name</a></li>
<li><a href="#_description_2">Description</a></li>
<li><a href="#_webservice">WebService</a></li>
<li><a href="#_log">Log</a></li>
<li><a href="#_oauth">OAuth</a></li>
<li><a href="#_session">Session</a></li>
<li><a href="#_bugs_2">Bugs</a></li>
<li><a href="#_author_2">Author</a></li>
<li><a href="#_see_also_2">See also</a></li>
</ul>
</li>
<li><a href="#_cockpit_ws8">cockpit-ws(8)</a>
<ul class="sectlevel3">
<li><a href="#_name_3">Name</a></li>
<li><a href="#_synopsis">Synopsis</a></li>
<li><a href="#_description_3">Description</a></li>
<li><a href="#_transport_security">Transport security</a></li>
<li><a href="#_timeout">Timeout</a></li>
<li><a href="#_options">Options</a></li>
<li><a href="#_environment">Environment</a></li>
<li><a href="#_bugs_3">Bugs</a></li>
<li><a href="#_author_3">Author</a></li>
<li><a href="#_see_also_3">See also</a></li>
</ul>
</li>
<li><a href="#_cockpit_tls8">cockpit-tls(8)</a>
<ul class="sectlevel3">
<li><a href="#_name_4">Name</a></li>
<li><a href="#_synopsis_2">Synopsis</a></li>
<li><a href="#_description_4">Description</a></li>
<li><a href="#_transport_security_2">Transport security</a></li>
<li><a href="#_options_2">Options</a></li>
<li><a href="#_environment_2">Environment</a></li>
<li><a href="#_bugs_4">Bugs</a></li>
<li><a href="#_author_4">Author</a></li>
<li><a href="#_see_also_4">See also</a></li>
</ul>
</li>
<li><a href="#_cockpit_desktop1">cockpit-desktop(1)</a>
<ul class="sectlevel3">
<li><a href="#_name_5">Name</a></li>
<li><a href="#_synopsis_3">Synopsis</a></li>
<li><a href="#_description_5">Description</a></li>
<li><a href="#_environment_3">Environment</a></li>
<li><a href="#_bugs_5">Bugs</a></li>
<li><a href="#_author_5">Author</a></li>
<li><a href="#_see_also_5">See also</a></li>
</ul>
</li>
<li><a href="#_cockpit_bridge1">cockpit-bridge(1)</a>
<ul class="sectlevel3">
<li><a href="#_name_6">Name</a></li>
<li><a href="#_synopsis_4">Synopsis</a></li>
<li><a href="#_description_6">Description</a></li>
<li><a href="#_options_3">Options</a></li>
<li><a href="#_bugs_6">Bugs</a></li>
<li><a href="#_author_6">Author</a></li>
<li><a href="#_see_also_6">See also</a></li>
</ul>
</li>
<li><a href="#_pam_ssh_add8">pam_ssh_add(8)</a>
<ul class="sectlevel3">
<li><a href="#_name_7">Name</a></li>
<li><a href="#_description_7">Description</a></li>
<li><a href="#_options_4">Options</a></li>
<li><a href="#_examples">Examples</a></li>
<li><a href="#_bugs_7">Bugs</a></li>
<li><a href="#_author_7">Author</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#https">SSL/TLS Usage</a>
<ul class="sectlevel2">
<li><a href="#https-required">HTTPS Requirement</a></li>
<li><a href="#https-certificates">Certificates</a></li>
</ul>
</li>
<li><a href="#listen">TCP Port and Address</a>
<ul class="sectlevel2">
<li><a href="#listen-systemd">Cockpit systemd Socket</a></li>
<li><a href="#listen-selinux">SELinux Port</a></li>
<li><a href="#listen-firewalld">Firewalld Port</a></li>
</ul>
</li>
<li><a href="#startup">Start up</a>
<ul class="sectlevel2">
<li><a href="#startup-shutdown">Process exit</a></li>
<li><a href="#startup-boot">Boot start up</a></li>
</ul>
</li>
<li><a href="#multi-host">Managing multiple hosts at the same time</a></li>
<li><a href="#authentication">Cockpit Authentication</a>
<ul class="sectlevel2">
<li><a href="#initial-auth">Directly logging into the primary server</a></li>
<li><a href="#direct-secondary-auth">Directly logging into a secondary server without a primary session</a></li>
<li><a href="#secondary-auth">Logging into a secondary server from the primary session</a>
<ul class="sectlevel3">
<li><a href="#_password">Password</a></li>
<li><a href="#_kerberos">Kerberos</a></li>
<li><a href="#_public_key">Public key</a></li>
<li><a href="#host-keys">SSH host keys</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#sso">Single Sign On</a>
<ul class="sectlevel2">
<li><a href="#sso-server">Server Requirements</a></li>
<li><a href="#sso-client">Client Requirements</a></li>
</ul>
</li>
<li><a href="#cert-authentication">Certificate/smart card authentication</a>
<ul class="sectlevel2">
<li><a href="#certauth-server-cert-generation">User certificate generation</a></li>
<li><a href="#certauth-server-ipa">Certificate mapping with FreeIPA</a></li>
<li><a href="#certauth-server-ms-ad">Certificate mapping with Microsoft Active Directory</a></li>
<li><a href="#certauth-server-samba-ad">Certificate mapping with Samba Active Directory</a></li>
<li><a href="#certauth-server-cockpitconf">Cockpit web server configuration</a></li>
<li><a href="#certauth-server-resourcelimits">Cockpit web server resource limits</a></li>
<li><a href="#certauth-forwarding">Authentication to other services like sudo and ssh</a></li>
</ul>
</li>
<li><a href="#privileges">Privileges and Permissions</a>
<ul class="sectlevel2">
<li><a href="#privileges-polkit">Customizing Polkit Privileges</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Documentation for Cockpit 355.</p>
</div>
<div class="paragraph">
<p>Latest version <a href="https://cockpit-project.org/guide/latest">available here</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="cockpit-manual">Manual pages</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="_cockpit1">cockpit(1)</h3>
<div class="sect3">
<h4 id="_name">Name</h4>
<div class="paragraph">
<p>cockpit - Cockpit</p>
</div>
</div>
<div class="sect3">
<h4 id="_description">Description</h4>
<div class="paragraph">
<p>Cockpit is a web accessible interactive admin interface for Linux
machines. Cockpit can usually be accessed on port <code>9090</code> of the
machine it&#8217;s installed on. Cockpit starts on demand. Use your system
credentials to log in.</p>
</div>
</div>
<div class="sect3">
<h4 id="_components">Components</h4>
<div class="paragraph">
<p>The <strong>cockpit-ws</strong> web service listens on port <code>9090</code> and is started
on demand by <strong>systemd</strong>. The Cockpit web service authenticates the
user, loads Cockpit into the browser, and starts <strong>cockpit-bridge</strong> in a
Linux user session.</p>
</div>
<div class="paragraph">
<p>The <strong>cockpit-bridge</strong> provides Cockpit in the web browser with access
to the system APIs. It does this over its standard in and standard out.
The bridge is started like a shell once per Linux user session.</p>
</div>
</div>
<div class="sect3">
<h4 id="_bugs">Bugs</h4>
<div class="paragraph">
<p>Please send bug reports to either the distribution bug tracker or the <a href="https://github.com/cockpit-project/cockpit/issues/new">upstream bug tracker</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_author">Author</h4>
<div class="paragraph">
<p>Cockpit has been written by many
<a href="https://github.com/cockpit-project/cockpit">contributors</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_see_also">See also</h4>
<div class="paragraph">
<p><strong>cockpit-tls(8)</strong> , <strong>cockpit.bridge(1)</strong> , <strong>systemd(1)</strong>, <strong><a href="https://cockpit-project.org/guide/latest">Cockpit guide</a></strong></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_cockpit_conf5">cockpit.conf(5)</h3>
<div class="sect3">
<h4 id="_name_2">Name</h4>
<div class="paragraph">
<p>cockpit.conf - Cockpit configuration file</p>
</div>
</div>
<div class="sect3">
<h4 id="_description_2">Description</h4>
<div class="paragraph">
<p>Cockpit can be configured via /etc/cockpit/cockpit.conf. If
<strong>$XDG_CONFIG_DIRS</strong> is set, then the first path containing a
<strong>../cockpit/cockpit.conf</strong> is used instead. Other configuration files
and directories are searched for in the same way.</p>
</div>
<div class="paragraph">
<p>This file is not required and may need to be created manually. The file
has a INI file syntax and thus contains key / value pairs, grouped into
topical groups. See the examples below for details.</p>
</div>
<div class="paragraph">
<p>Note: The port that cockpit listens on cannot be changed in this file.
To change the port change the systemd <strong>cockpit.socket</strong> file.</p>
</div>
</div>
<div class="sect3">
<h4 id="_webservice">WebService</h4>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>Origins</strong></dt>
<dd>
<p>By default cockpit will not accept crossdomain websocket connections.
Use this setting to allow access from alternate domains. Origins
should include scheme, host and port, if necessary. Wildcards and glob
expressions are permitted.
<br></p>
</dd>
</dl>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[WebService]
Origins = https://somedomain1.com https://somedomain2.com:9090 https://*.somedomain3.com</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>ProtocolHeader</strong></dt>
<dd>
<p>Configure cockpit to look at the contents of this header to determine
if a connection is using tls. This should only be used when cockpit is
behind a reverse proxy, and care should be taken to make sure that
incoming requests cannot set this header.
<br></p>
</dd>
</dl>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[WebService]
ProtocolHeader = X-Forwarded-Proto</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>ForwardedForHeader</strong></dt>
<dd>
<p>Configure cockpit to look at the contents of this header to determine
the real origin of a connection. This should only be used when cockpit
is behind a reverse proxy, and care should be taken to make sure that
incoming requests cannot set this header.
<br></p>
</dd>
</dl>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[WebService]
ForwardedForHeader = X-Forwarded-For</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>LoginTitle</strong></dt>
<dd>
<p>Set the browser title for the login screen.</p>
</dd>
<dt class="hdlist1"><strong>LoginTo</strong></dt>
<dd>
<p>When set to <code>true</code> the <em>Connect to</em> option on the login screen is
visible and allows logging into another server. When set to <code>false</code>,
direct remote logins are disallowed. If this option is not specified
then it will be automatically detected based on whether the
<strong>cockpit-bridge</strong> package is installed and the <strong>ssh</strong> program is
available.<br>
<br>
If cockpit-ws is exposed to the public internet, and also has access
to a private internal network, it is recommended to explicitly set
<strong>LoginTo=false</strong>. This prevents unauthenticated remote attackers from
scanning the internal network for existing machines and open ports.</p>
</dd>
<dt class="hdlist1"><strong>RequireHost</strong></dt>
<dd>
<p>When set to <code>true</code> cockpit will require users to use the <em>Connect
to</em> option to specify the host to log into.</p>
</dd>
<dt class="hdlist1"><strong>AllowMultiHost</strong></dt>
<dd>
<p>When set to <code>true</code>, cockpit will allow users to connect to multiple
hosts in one session. The default is OS specific.<br>
<br>
When connecting to multiple servers, JavaScript runs without
isolation. All systems will be vulnerable to potential attacks from
other connected hosts. Enable this option <em>only</em> when all hosts are
trusted.</p>
</dd>
<dt class="hdlist1"><strong>MaxStartups</strong></dt>
<dd>
<p>Same as the <strong>sshd</strong> configuration option by the same name. Specifies
the maximum number of concurrent login attempts allowed. Additional
connections will be dropped until authentication succeeds or the
connections are closed. Defaults to 10.<br>
<br>
Alternatively, random early drop can be enabled by specifying the
three colon separated values <strong>start:rate:full</strong> (e.g. "10:30:60").
Cockpit will start refusing authentication attempts with a probability
of <strong>rate/100</strong> (30%) if there are currently <strong>start</strong> (10)
unauthenticated connections. The probability increases linearly and
all connection attempts are refused if the number of unauthenticated
connections reaches <strong>full</strong> (60).</p>
</dd>
<dt class="hdlist1"><strong>AllowUnencrypted</strong></dt>
<dd>
<p>If true, cockpit will accept unencrypted HTTP connections. Otherwise,
it redirects all HTTP connections to HTTPS. Exceptions are connections
from localhost and for certain URLs (like <strong>/ping</strong>). Defaults to
false.</p>
</dd>
<dt class="hdlist1"><strong>UrlRoot</strong></dt>
<dd>
<p>The root URL where you will be serving cockpit. When provided cockpit
will expect all requests to be prefixed with the given url. This is
mostly useful when you are using cockpit behind a reverse proxy, such
as nginx. <code>/cockpit/</code> and <code>/cockpit+</code> are reserved and should not
be used. For example <code>/cockpit-new/</code> is ok. <code>/cockpit/</code> and
<code>/cockpit+new/</code> are not.</p>
</dd>
<dt class="hdlist1"><strong>ClientCertAuthentication</strong></dt>
<dd>
<p>If true, enable TLS client certificates for authenticating users.
Commonly these are provided by a smart card, but it&#8217;s equally possible
to import certificates directly into the web browser. Please see the
<a href="https://cockpit-project.org/guide/latest/cert-authentication.html">Certificate/smart
card authentication</a> section in the Cockpit guide for details.</p>
</dd>
<dt class="hdlist1"><strong>Shell</strong></dt>
<dd>
<p>The relative URL to top level component to display in Cockpit once
logged in. Defaults to <code>/shell/index.html</code></p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="_log">Log</h4>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>Fatal</strong></dt>
<dd>
<p>The kind of log messages in the bridge to treat as fatal. Separate
multiple values with spaces. Relevant values are: <strong>criticals</strong> and
<strong>warnings</strong>.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="_oauth">OAuth</h4>
<div class="paragraph">
<p>Cockpit can be configured to support the
<a href="https://tools.ietf.org/html/rfc6749#section-4.2">implicit grant</a> OAuth
authorization flow. When successful the resulting oauth token will be
passed to cockpit-ws using the <strong>Bearer</strong> auth-scheme. For a login to be
successful, cockpit will also need a to be configured to verify and
allow <strong>Bearer</strong> tokens.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>URL</strong></dt>
<dd>
<p>This is the url that cockpit will redirect the users browser to when
it needs to obtain an oauth token. Cockpit will add a redirect_uri
parameter to the url with the location of where the oauth provider
should redirect to once a token has been obtained.</p>
</dd>
<dt class="hdlist1"><strong>ErrorParam</strong></dt>
<dd>
<p>When a oauth provider redirects a user back to cockpit, look for this
parameter in the querystring or fragment portion of the url to find a
error message. When not provided it will default to
<strong>error_description</strong></p>
</dd>
<dt class="hdlist1"><strong>TokenParam</strong></dt>
<dd>
<p>When a oauth provider redirects a user back to cockpit, look for this
parameter in the querystring or fragment portion of the url to find
the access token. When not provided it will default to
<strong>access_token</strong></p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="_session">Session</h4>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>Banner</strong></dt>
<dd>
<p>The contents of the specified file (commonly <strong>/etc/issue</strong>) are shown
on the login page. By default, no banner is displayed.</p>
</dd>
<dt class="hdlist1"><strong>IdleTimeout</strong></dt>
<dd>
<p>Time in minutes after which session expires and user is logged out if
no user action has been performed in the given time. This idle timeout
only applies to interactive password logins. With non-interactive
authentication methods like Kerberos, OAuth, or certificate login, the
browser cannot forget credentials, and thus automatic logouts are not
useful for protecting credentials of forgotten sessions. Set to <strong>0</strong>
to disable session timeout.
<br></p>
</dd>
</dl>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[Session]
IdleTimeout=15</code></pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"></dt>
<dd>
<p>When not specified, there is no idle timeout by default.</p>
</dd>
<dt class="hdlist1"><strong>WarnBeforeConnecting</strong></dt>
<dd>
<p>Whether to warn before connecting to remote hosts from the Shell.
Defaults to true.
<br></p>
</dd>
</dl>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-ini" data-lang="ini">[Session]
WarnBeforeConnecting=false</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_bugs_2">Bugs</h4>
<div class="paragraph">
<p>Please send bug reports to either the distribution bug tracker or the <a href="https://github.com/cockpit-project/cockpit/issues/new">upstream bug tracker</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_author_2">Author</h4>
<div class="paragraph">
<p>Cockpit has been written by many
<a href="https://github.com/cockpit-project/cockpit">contributors</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_2">See also</h4>
<div class="paragraph">
<p><strong>cockpit-ws(8)</strong>, <strong>cockpit-tls(8)</strong></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_cockpit_ws8">cockpit-ws(8)</h3>
<div class="sect3">
<h4 id="_name_3">Name</h4>
<div class="paragraph">
<p>cockpit-ws - Cockpit web service</p>
</div>
</div>
<div class="sect3">
<h4 id="_synopsis">Synopsis</h4>
<div class="paragraph">
<p><strong>cockpit-ws</strong> [<strong>--help</strong>] [<strong>--port</strong> <em>PORT</em>] [<strong>--address</strong> <em>ADDRESS</em>] [<strong>--no-tls</strong>]
			 [<strong>--for-tls-proxy</strong>] [<strong>--local-ssh</strong>] [<strong>--local-session</strong> <em>BRIDGE</em>]</p>
</div>
</div>
<div class="sect3">
<h4 id="_description_3">Description</h4>
<div class="paragraph">
<p>The <strong>cockpit-ws</strong> program is the web service component used for
communication between the browser application and various configuration
tools and services like <strong>cockpit-bridge(1)</strong>.</p>
</div>
<div class="paragraph">
<p>Users or administrators should never need to start this program as it
automatically started by <strong>systemd(1)</strong> on bootup, through
<strong>cockpit-tls(8)</strong>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_transport_security">Transport security</h4>
<div class="paragraph">
<p><strong>cockpit-ws</strong> is normally run behind the <strong>cockpit-tls</strong> TLS
terminating proxy, and only deals with unencrypted HTTP by itself. But
for backwards compatibility it can also handle TLS connections by itself
when being run directly. For details how to configure certificates,
please refer to the <strong>cockpit-tls(8)</strong> documentation.</p>
</div>
</div>
<div class="sect3">
<h4 id="_timeout">Timeout</h4>
<div class="paragraph">
<p>When started via <strong>systemd(1)</strong> then <strong>cockpit-ws</strong> will exit after 90
seconds if nobody logs in, or after the last user is disconnected.</p>
</div>
</div>
<div class="sect3">
<h4 id="_options">Options</h4>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>--help</strong></dt>
<dd>
<p>Show help options.</p>
</dd>
<dt class="hdlist1"><strong>--port</strong> <em>PORT</em></dt>
<dd>
<p>Serve HTTP requests <em>PORT</em> instead of port <strong>9090</strong>. Usually Cockpit is
started on demand by <strong>systemd</strong> socket activation, and this option
has no effect. Update the <strong>ListenStream</strong> directive
<strong>cockpit.socket</strong> file in the usual <strong>systemd</strong> manner.</p>
</dd>
<dt class="hdlist1"><strong>--address</strong> <em>ADDRESS</em></dt>
<dd>
<p>Bind to address <em>ADDRESS</em> instead of binding to all available
addresses. Usually Cockpit is started on demand by <strong>systemd</strong> socket
activation, and this option has no effect. In that case, update the
<strong>ListenStream</strong> directive in the <strong>cockpit.socket</strong> file in the usual
<strong>systemd</strong> manner.</p>
</dd>
<dt class="hdlist1"><strong>--no-tls</strong></dt>
<dd>
<p>Disable http to https redirection.</p>
</dd>
<dt class="hdlist1"><strong>--for-tls-proxy</strong></dt>
<dd>
<p>Tell <strong>cockpit-ws</strong> that it is running behind a local reverse proxy
that does the TLS termination. Then Cockpit puts https:// URLs into
the default <strong>Content-Security-Policy</strong>, and accepts only https://
origins, instead of http: ones by default. However, if <strong>Origins</strong> is
set in the <strong>cockpit.conf(5)</strong> configuration file, it will override
this default.</p>
</dd>
<dt class="hdlist1"><strong>--local-ssh</strong></dt>
<dd>
<p>Normally <strong>cockpit-ws</strong> uses <strong>cockpit-session</strong> and PAM to
authenticate the user and start a user session. With this option
enabled, it will instead authenticate via SSH at <strong>127.0.0.1</strong> port
<strong>22</strong>.</p>
</dd>
<dt class="hdlist1"><strong>--local-session</strong> <em>BRIDGE</em></dt>
<dd>
<p>Skip all authentication and <strong>cockpit-session</strong>, and launch the
<strong>cockpit-bridge</strong> specified in <em>BRIDGE</em> in the local session. If the
<em>BRIDGE</em> is specified as <code>-</code> then expect an already running bridge
that is connected to stdin and stdout of this <strong>cockpit-ws</strong> process.
This allows the web server to run as any unprivileged user in an
already running session.<br>
<br>
This mode implies <strong>--no-tls</strong>, thus you need to use http:// URLs with
this.</p>
</dd>
</dl>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
<div class="paragraph">
<p>With <strong>--local-session</strong> <em>BRIDGE</em>, you <em>have to isolate the opened TCP port</em> somehow
(for example in a network namespace), otherwise all other users (or
even remote machines if the port is not just listening on localhost)
can access the session!</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="_environment">Environment</h4>
<div class="paragraph">
<p>The <strong>cockpit-ws</strong> process will use the <strong>XDG_CONFIG_DIRS</strong> environment
variable from the
<a href="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
basedir spec</a> to find its <strong>cockpit.conf(5)</strong> configuration file.</p>
</div>
<div class="paragraph">
<p>In addition the <strong>XDG_DATA_DIRS</strong> environment variable from the
<a href="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
basedir spec</a> can be used to override the location to serve static files
from. These are the files that are served to a non-logged in user.</p>
</div>
</div>
<div class="sect3">
<h4 id="_bugs_3">Bugs</h4>
<div class="paragraph">
<p>Please send bug reports to either the distribution bug tracker or the <a href="https://github.com/cockpit-project/cockpit/issues/new">upstream bug tracker</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_author_3">Author</h4>
<div class="paragraph">
<p>Cockpit has been written by many
<a href="https://github.com/cockpit-project/cockpit">contributors</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_3">See also</h4>
<div class="paragraph">
<p><strong>cockpit-tls(8)</strong> , <strong>cockpit.conf(5)</strong> , <strong>systemd(1)</strong></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_cockpit_tls8">cockpit-tls(8)</h3>
<div class="sect3">
<h4 id="_name_4">Name</h4>
<div class="paragraph">
<p>cockpit-tls - TLS proxy for Cockpit web service</p>
</div>
</div>
<div class="sect3">
<h4 id="_synopsis_2">Synopsis</h4>
<div class="paragraph">
<p><strong>cockpit-tls</strong> [<strong>--help</strong>] [<strong>--port</strong> <em>PORT</em>] [<strong>--no-tls</strong>] [<strong>--idle-timeout</strong> <em>SECONDS</em>]</p>
</div>
</div>
<div class="sect3">
<h4 id="_description_4">Description</h4>
<div class="paragraph">
<p>The <strong>cockpit-tls</strong> program is a TLS terminating HTTP proxy for
<strong>cockpit-ws(8)</strong>. It manages a set of isolated cockpit-ws instances,
one per TLS client certificate, plus one for TLS without a client
certificate, and one for unencrypted HTTP. With that, one session cannot
tamper with another one through possible security vulnerability
exploits.</p>
</div>
<div class="paragraph">
<p>Users or administrators should never need to start this program as it
automatically started by <strong>systemd(1)</strong> via socket activation.</p>
</div>
</div>
<div class="sect3">
<h4 id="_transport_security_2">Transport security</h4>
<div class="paragraph">
<p>To specify the TLS certificate the web service should use, simply drop a
file with the extension <strong>.cert</strong> in the <strong>/etc/cockpit/ws-certs.d</strong>
directory, or below <strong>$XDG_CONFIG_DIRS</strong> if set (see
<a href="./cockpit.conf.5.html">cockpit.conf</a>). If there are multiple files
in this directory, then the highest priority one is chosen after
sorting.</p>
</div>
<div class="paragraph">
<p>The <strong>.cert</strong> file should contain at least two OpenSSL style PEM blocks.
First one or more <code>BEGIN CERTIFICATE</code> blocks for the server
certificate and intermediate certificate authorities and a second one
containing a <code>BEGIN PRIVATE KEY</code> or similar. The key must not be
encrypted.</p>
</div>
<div class="paragraph">
<p>If there is no TLS certificate, a self-signed certificate is
automatically generated using <strong>sscg</strong> (if available) or <strong>openssl</strong> and
stored in the <strong>0-self-signed.cert</strong> file.</p>
</div>
<div class="paragraph">
<p>When enrolling into a FreeIPA domain, an SSL certificate is requested
from the IPA server and stored in <strong>10-ipa.cert</strong>.</p>
</div>
<div class="paragraph">
<p>To check which certificate <strong>cockpit-ws</strong> will use, run the following
command.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo /usr/libexec/cockpit-certificate-ensure --check</pre>
</div>
</div>
<div class="paragraph">
<p>Or, on Debian-based systems:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo /usr/lib/cockpit/cockpit-certificate-ensure --check</pre>
</div>
</div>
<div class="paragraph">
<p>If using <strong>certmonger</strong> to manage certificates, following command can be
used to generate a certificate/key pair:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>CERT_FILE=/etc/cockpit/ws-certs.d/50-certmonger.crt
KEY_FILE=/etc/cockpit/ws-certs.d/50-certmonger.key

getcert request -f ${CERT_FILE} -k ${KEY_FILE} -D $(hostname --fqdn)</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_options_2">Options</h4>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>--help</strong></dt>
<dd>
<p>Show help options.</p>
</dd>
<dt class="hdlist1"><strong>--port</strong> <em>PORT</em></dt>
<dd>
<p>Serve HTTP requests on <em>PORT</em> instead of port 9090. Usually Cockpit is
started on demand by <strong>systemd</strong> socket activation, and this option
has no effect. Update the <strong>ListenStream</strong> directive
<strong>cockpit.socket</strong> file in the usual <strong>systemd</strong> manner.</p>
</dd>
<dt class="hdlist1"><strong>--no-tls</strong></dt>
<dd>
<p>Don&#8217;t use TLS. Certificates will not be read, and https connections
denied. Then <strong>cockpit-tls</strong> will only manage a single cockpit-ws
instance, and thus not do anything different than running
<strong>cockpit-ws --no-tls</strong> directly. Only use this for debugging or
testing.</p>
</dd>
<dt class="hdlist1"><strong>--idle-timeout</strong> <em>SECONDS</em></dt>
<dd>
<p>If greater than 0, exit if no connections have happened for the given
number of seconds, i. e. the server is idle. If not given, the default
is 90.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="_environment_2">Environment</h4>
<div class="paragraph">
<p>The <strong>cockpit-tls</strong> program expects the <strong>RUNTIME_DIRECTORY</strong>
environment variable to be set to an empty directory (preferably in
<strong>/run/</strong>) that is only accessible by the system user under which it is
running. This contains the Unix sockets for communicating with the
<strong>cockpit-ws</strong> instances, and in the future, state information about
client certificates. This variable is normally set by the
<strong>cockpit.service</strong> systemd unit.</p>
</div>
<div class="paragraph">
<p>In addition, <strong>cockpit-tls</strong> will use the <strong>XDG_CONFIG_DIRS</strong>
environment variable from the
<a href="https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
basedir spec</a> to find its certificates and the <strong>cockpit.conf(5)</strong>
configuration file.</p>
</div>
</div>
<div class="sect3">
<h4 id="_bugs_4">Bugs</h4>
<div class="paragraph">
<p>Please send bug reports to either the distribution bug tracker or the <a href="https://github.com/cockpit-project/cockpit/issues/new">upstream bug tracker</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_author_4">Author</h4>
<div class="paragraph">
<p>Cockpit has been written by many
<a href="https://github.com/cockpit-project/cockpit">contributors</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_4">See also</h4>
<div class="paragraph">
<p><strong>cockpit-ws(8)</strong> , <strong>cockpit.conf(5)</strong> , <strong>systemd(1)</strong></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_cockpit_desktop1">cockpit-desktop(1)</h3>
<div class="sect3">
<h4 id="_name_5">Name</h4>
<div class="paragraph">
<p>cockpit-desktop - Cockpit Desktop integration</p>
</div>
</div>
<div class="sect3">
<h4 id="_synopsis_3">Synopsis</h4>
<div class="paragraph">
<p><strong>cockpit-desktop</strong> <em>URLPATH</em> [<em>SSH_HOST</em>]</p>
</div>
</div>
<div class="sect3">
<h4 id="_description_5">Description</h4>
<div class="paragraph">
<p>The <strong>cockpit-desktop</strong> program provides secure access to Cockpit pages
in an already running desktop session. It starts a web server
(<strong>cockpit-ws</strong>) and a web browser in an isolated network namespace, and
a <strong>cockpit-bridge(8)</strong> in the running user session.</p>
</div>
<div class="paragraph">
<p>This avoids having to log into Cockpit, and having to enable
<strong>cockpit.socket</strong> system-wide. The network isolation ensures that no
other user, and not even other processes in the user&#8217;s session, can
access this local web server.</p>
</div>
<div class="paragraph">
<p><strong>URLPATH</strong> is the Cockpit page to open, i. e. the path component of
Cockpit URLs. It is highly recommended to only open a
<a href="https://cockpit-project.org/guide/latest/embedding.html">particular page frame</a>, not the entire Cockpit navigation and menu. For example, the
path <code>/cockpit/@localhost/storage/index.html</code> will open the Storage
page. It is also possible to give abbreviated forms of urls, such as
&#8220;/storage&#8221; or &#8220;/network/firewall&#8221;.</p>
</div>
<div class="paragraph">
<p><em>SSH_HOST</em> is an optional SSH remote host specification (<em>hostname</em>
or <em>username@hostname</em>). If given, <strong>cockpit-bridge</strong> will be started
on the remote host through <strong>ssh(1)</strong> instead, i. e. the Cockpit web
browser will show that remote host. Note that this is more of an
experimental/demo feature.</p>
</div>
</div>
<div class="sect3">
<h4 id="_environment_3">Environment</h4>
<div class="paragraph">
<p>The <strong>BROWSER</strong> environment variable specifies the browser command (and
possibly options) that will be used to open the requested Cockpit page.
If not set, <strong>cockpit-desktop</strong> attempts to use an internal minimalistic
WebKit browser, and failing that, will attempt to detect some reasonable
alternatives.</p>
</div>
</div>
<div class="sect3">
<h4 id="_bugs_5">Bugs</h4>
<div class="paragraph">
<p>Please send bug reports to either the distribution bug tracker or the <a href="https://github.com/cockpit-project/cockpit/issues/new">upstream bug tracker</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_author_5">Author</h4>
<div class="paragraph">
<p>Cockpit has been written by many
<a href="https://github.com/cockpit-project/cockpit">contributors</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_5">See also</h4>
<div class="paragraph">
<p><strong>cockpit-ws(8)</strong>, <strong>cockpit-bridge(1)</strong></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_cockpit_bridge1">cockpit-bridge(1)</h3>
<div class="sect3">
<h4 id="_name_6">Name</h4>
<div class="paragraph">
<p>cockpit-bridge - Cockpit Host Bridge</p>
</div>
</div>
<div class="sect3">
<h4 id="_synopsis_4">Synopsis</h4>
<div class="paragraph">
<p><strong>cockpit-bridge</strong> [<strong>--help</strong>] [<strong>--packages</strong>]</p>
</div>
</div>
<div class="sect3">
<h4 id="_description_6">Description</h4>
<div class="paragraph">
<p>The <strong>cockpit-bridge</strong> program is used by Cockpit to relay messages and
commands from the Web front end to the server. Among other things it
relays DBus, and spawns processes on behalf of the Web user interface.</p>
</div>
<div class="paragraph">
<p>This program is not routinely run by users or administrators. It is in
the <strong>$PATH</strong> so that Cockpit can find it when connecting between hosts.
However there are some diagnostics available when running from the
command line.</p>
</div>
</div>
<div class="sect3">
<h4 id="_options_3">Options</h4>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>--help</strong></dt>
<dd>
<p>Show help options.</p>
</dd>
<dt class="hdlist1"><strong>--interact</strong>=<em>boundary</em></dt>
<dd>
<p>Interact with the raw cockpit1 protocol. Useful for debugging and
testing. Specify a <em>boundary</em> which should be on an empty line
between messages.</p>
</dd>
<dt class="hdlist1"><strong>--packages</strong></dt>
<dd>
<p>List all available Cockpit packages and exit. Note this includes
packages available to the user running this command.</p>
</dd>
<dt class="hdlist1"><strong>--version</strong></dt>
<dd>
<p>Show Cockpit version information.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="_bugs_6">Bugs</h4>
<div class="paragraph">
<p>Please send bug reports to either the distribution bug tracker or the <a href="https://github.com/cockpit-project/cockpit/issues/new">upstream bug tracker</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_author_6">Author</h4>
<div class="paragraph">
<p>Cockpit has been written by many
<a href="https://github.com/cockpit-project/cockpit">contributors</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_see_also_6">See also</h4>
<div class="paragraph">
<p><strong>cockpit-ws(8)</strong></p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_pam_ssh_add8">pam_ssh_add(8)</h3>
<div class="sect3">
<h4 id="_name_7">Name</h4>
<div class="paragraph">
<p>pam_ssh_add - PAM module to auto load ssh keys into an agent</p>
</div>
</div>
<div class="sect3">
<h4 id="_description_7">Description</h4>
<div class="paragraph">
<p><strong>pam_ssh_add</strong> provides authentication and session modules that allow users
to start their session with a running ssh-agent with as many ssh keys
loaded as possible.</p>
</div>
<div class="paragraph">
<p>If used, the authentication module simply stores the authentication
token for later use by the session module. Because this module performs
no actual authentication it returns PAM_CRED_INSUFFICIENT on success and
should always be accompanied by an actual authentication module in your
pam configuration.</p>
</div>
<div class="paragraph">
<p>By default the session module will start a new ssh-agent and run
ssh-add, loading any keys that exist in the default path for the newly
logged in user. If any keys prompt for a password, and a authentication
token was successfully stored, that token will be provided as the
password.</p>
</div>
</div>
<div class="sect3">
<h4 id="_options_4">Options</h4>
<div class="dlist">
<dl>
<dt class="hdlist1"><strong>debug</strong></dt>
<dd>
<p>This option will turn on debug logging to syslog.</p>
</dd>
</dl>
</div>
</div>
<div class="sect3">
<h4 id="_examples">Examples</h4>
<div class="literalblock">
<div class="content">
<pre>        auth     required  pam_unix.so
        auth     optional  pam_ssh_add.so
        session  optional  pam_ssh_add.so</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_bugs_7">Bugs</h4>
<div class="paragraph">
<p>Please send bug reports to either the distribution bug tracker or the <a href="https://github.com/cockpit-project/cockpit/issues/new">upstream bug tracker</a>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_author_7">Author</h4>
<div class="paragraph">
<p>Cockpit has been written by many
<a href="https://github.com/cockpit-project/cockpit">contributors</a>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="https">SSL/TLS Usage</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Cockpit usually requires that web browsers communicate with it using
HTTPS, for security reasons.</p>
</div>
<div class="sect2">
<h3 id="https-required">HTTPS Requirement</h3>
<div class="paragraph">
<p>Cockpit listens for both HTTP and HTTPS connections on the same port, by
default 9090. If an HTTP connection is made, Cockpit will redirect that
connection to HTTPS. There are some exceptions:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>If an HTTP connection comes from <code>localhost</code> (<code>127.0.0.1</code> or
<code>::1</code>, then Cockpit will allow communication without redirecting to
HTTPS.</p>
</li>
<li>
<p>Certain URLs, like <code>/ping</code> are not required to use HTTPS.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>This behavior can be overridden by setting the <code>AllowUnencrypted</code>
option in <code>cockpit.conf</code>.</p>
</div>
</div>
<div class="sect2">
<h3 id="https-certificates">Certificates</h3>
<div class="paragraph">
<p>Cockpit will load a certificate from the <code>/etc/cockpit/ws-certs.d</code>,
directory, or below <code>$XDG_CONFIG_DIRS</code> if set (see
<a href="./cockpit.conf.5.html">cockpit.conf</a>). It will use the last file
with a <code>.cert</code> or <code>.crt</code> extension in alphabetical order. The file
should contain one or more OpenSSL style <code>BEGIN CERTIFICATE</code> blocks
for the server certificate and the intermediate certificate authorities.</p>
</div>
<div class="paragraph">
<p>The private key must be contained in a separate file with the same name
as the certificate, but with a <code>.key</code> suffix instead. The key must not
be encrypted.</p>
</div>
<div class="paragraph">
<p>If no certificate is found, a self-signed certificate is created and
stored in the <code>0-self-signed.cert</code> file. On some platforms, Cockpit
will also generate a ca.crt in that directory, which may be safely
imported into client browsers.</p>
</div>
<div class="paragraph">
<p>Cockpit will read the files as root, so they can have tight permissions.</p>
</div>
<div class="paragraph">
<p>To check which certificate <code>cockpit-ws</code> will use run the following
command.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo /usr/libexec/cockpit-certificate-ensure --check</pre>
</div>
</div>
<div class="paragraph">
<p>Or, on Debian-based systems:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo /usr/lib/cockpit/cockpit-certificate-ensure --check</pre>
</div>
</div>
<div class="paragraph">
<p>If using <code>certmonger</code> to manage certificates, following command can be
used to automatically prepare a certificate/key file pair:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>getcert request -f /etc/cockpit/ws-certs.d/50-certmonger.cert \
                -k /etc/cockpit/ws-certs.d/50-certmonger.key \
                -D myhostname.example.com \
                [--ca=...]</pre>
</div>
</div>
<div class="paragraph">
<p>This will not work on Red Hat Enterprise Linux 8 by default. Adjust the
SELinux type of the certificate directory to <code>cert_t</code> to allow
certmonger to write its certificates there:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>semanage fcontext -a -t cert_t '/etc/cockpit/ws-certs\.d(/.*)?'
restorecon -v /etc/cockpit/ws-certs.d</pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="listen">TCP Port and Address</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Cockpit&#8217;s <code>cockpit-ws</code> component is configured by default to accept
connections on port <code>9090</code>. This is the port that is documented for a
"Web-based System Manager" to listen on. It is also relatively
memorable.</p>
</div>
<div class="paragraph">
<p>However there are many reasons you may wish to change the default port.
For example other software may use port <code>9090</code> or you may wish to
setup Cockpit to listen on <code>443</code> instead. It is also possible to have
Cockpit only listen on one specific IP address.</p>
</div>
<div class="paragraph">
<p>Note that it is only required to have Cockpit listening on a TCP port on
the server that you access with your web browser. If you add multiple
servers with host switcher, Cockpit will connect to those servers via
<code>ssh</code>.</p>
</div>
<div class="paragraph">
<p>The systems that Cockpit runs on are typically locked down with
firewalls, SELinux, so changing the default port is not as easy as
editing a configuration file.</p>
</div>
<div class="sect2">
<h3 id="listen-systemd">Cockpit systemd Socket</h3>
<div class="paragraph">
<p>On servers with
<a href="https://www.freedesktop.org/wiki/Software/systemd/"><code>systemd</code></a> Cockpit
starts on demand via socket activation. To change its port and/or
address you should place the following content in the
<code>/etc/systemd/system/cockpit.socket.d/listen.conf</code> file. Create the
file and directories in that path which not already exist. The
<code>ListenStream</code> option specifies the desired address and TCP port.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[Socket]
ListenStream=
ListenStream=443</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>[Socket]
ListenStream=
ListenStream=7777
ListenStream=192.168.1.1:443
FreeBind=yes</pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
The first line with an empty value is intentional. <code>systemd</code>
allows multiple <code>Listen</code> directives to be declared in a single socket
unit; an empty value in a drop-in file resets the list and thus disables
the default port 9090 from the original unit.
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>The <code>FreeBind</code> option is highly recommended when defining specific IP
addresses. See the
<a href="https://www.freedesktop.org/software/systemd/man/systemd.socket.html"><code>systemd.socket</code>
manpage</a> for details.</p>
</div>
<div class="paragraph">
<p>In order for the changes to take effect, run the following commands:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo systemctl daemon-reload
$ sudo systemctl restart cockpit.socket</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="listen-selinux">SELinux Port</h3>
<div class="paragraph">
<p>If <a href="https://selinuxproject.org/page/Main_Page">SELinux</a> is protecting your
server, then you will need to tell it to allow Cockpit to listen on the
new port. Run the following command to do so. The last argument
specifies the desired TCP port.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo semanage port -a -t websm_port_t -p tcp 9999</pre>
</div>
</div>
<div class="paragraph">
<p>If the port is already defined by some other part of the SELinux policy,
then you will need to use the <code>-m</code> argument to modify the definition.
That&#8217;s the case with the <code>443</code> SSL port, which is typically defined as
an <code>http_port_t</code> port.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo semanage port -m -t websm_port_t -p tcp 443</pre>
</div>
</div>
<div class="paragraph">
<p>The changes should take effect immediately.</p>
</div>
</div>
<div class="sect2">
<h3 id="listen-firewalld">Firewalld Port</h3>
<div class="paragraph">
<p>If <a href="https://fedoraproject.org/wiki/FirewallD">Firewalld</a> is configured as
your firewall, then you will need to tell it to allow Cockpit to receive
connections on the new port. Run the following commands to do so. The
last options specify the desired TCP port.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo firewall-cmd [--zone=ZONE] --add-port=443/tcp
$ sudo firewall-cmd --permanent [--zone=ZONE] --add-port=443/tcp</pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="startup">Start up</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Cockpit&#8217;s <code>cockpit-ws</code> component is what the browser connects to and
it typically starts on demand via
<a href="https://www.freedesktop.org/wiki/Software/systemd/"><code>systemd</code></a> socket
activation.</p>
</div>
<div class="paragraph">
<p>The actual <code>cockpit.service</code> and <code>cockpit-ws</code> process will start on
demand when a browser accesses the <code>cockpit.socket</code>,
<a href="#listen">usually on port 9090</a>. Once a user logs in then a
<code>cockpit-bridge</code> process will be started in a Linux user login
session.</p>
</div>
<div class="paragraph">
<p>Only systems that you connect to with your browser need to have the
<code>cockpit.socket</code> enabled. For systems that you add through host
switcher the bridge is started via SSH on demand.</p>
</div>
<div class="sect2">
<h3 id="startup-shutdown">Process exit</h3>
<div class="paragraph">
<p>The <code>cockpit-bridge</code> process will exit when the user logs out. In
addition, after 10 minutes of inactivity, the <code>cockpit-ws</code> process
will exit on its own. The browser will automatically disconnect if it
fails to hear from the <code>cockpit-ws</code> process for 30 seconds.</p>
</div>
</div>
<div class="sect2">
<h3 id="startup-boot">Boot start up</h3>
<div class="paragraph">
<p>To make Cockpit available by default after system boot the
<code>cockpit.socket</code> needs to be enabled:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo systemctl enable cockpit.socket</pre>
</div>
</div>
<div class="paragraph">
<p>If you wish to not have Cockpit available by default via a browser, then
the <code>cockpit.socket</code> should be disabled:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo systemctl disable cockpit.socket</pre>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="multi-host">Managing multiple hosts at the same time</h2>
<div class="sectionbody">
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
<div class="paragraph">
<p>This feature is deprecated as of Cockpit 322.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Cockpit allows you to access multiple hosts in a single session, by
establishing SSH connections to other hosts. This is quite similar to
logging into these other hosts using the <code>ssh</code> command on the command
line, with one very important difference:</p>
</div>
<div class="paragraph">
<p>Code from the local host and all the remote hosts run at the same time,
in the same browser context. They are not isolated from each other in
the browser. All code effectively has the same privileges as the primary
session on the local host.</p>
</div>
<div class="paragraph">
<p>Thus, <em>you should only only connect to remote hosts that you trust</em>. You
must be sure that none of the hosts that you connect to will cause
Cockpit to load malicious JavaScript code into your browser.</p>
</div>
<div class="paragraph">
<p>Therefore, Cockpit will warn you before connecting to more than one
host. It is also possible to disable multiple hosts entirely, and some
operating systems do this already by default.</p>
</div>
<div class="paragraph">
<p>You can prevent loading of JavaScript, HTML, etc from more than one host
by adding this to <code>cockpit.conf</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>    [WebService]
    AllowMultiHost=false</pre>
</div>
</div>
<div class="paragraph">
<p>When you allow multiple hosts in a single Cockpit session by setting
<code>AllowMultiHost</code> to true, then the user will be warned once per
session, before connecting to the second host. If that is still too
much, you can switch the warning off completely by adding the following
to <code>cockpit.conf</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>    [Session]
    WarnBeforeConnecting=false</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="authentication">Cockpit Authentication</h2>
<div class="sectionbody">
<div class="paragraph">
<p>While cockpit allows you to monitor and administer several servers at
the same time, there is always a primary server your browser connects to
that runs the Cockpit web service (cockpit-ws) through which connections
to additional servers are established. See
<a href="https://raw.githubusercontent.com/cockpit-project/cockpit/main/doc/cockpit-transport.png">this
diagram</a> for how it works.</p>
</div>
<div class="paragraph">
<p>Normally, a session is established on the primary server, and you use
the Shell UI of that session to connect to secondary servers.</p>
</div>
<div class="paragraph">
<p>However, it is also possible to instruct the <code>cockpit-ws</code> process on
the primary server to directly connect to a secondary server, without
opening a session on the primary server at all. This is done on the main
login page of Cockpit, by filling out the "Connect to" field.</p>
</div>
<div class="sect2">
<h3 id="initial-auth">Directly logging into the primary server</h3>
<div class="paragraph">
<p>The most common way to use Cockpit is to just log directly into the
server that you want to access. This can be done if you have direct
network access to port 9090 on that server.</p>
</div>
<div class="paragraph">
<p>By default the cockpit web service is installed on the base system and
<a href="#listen">socket activated by systemd</a>. In this setup access is
controlled by a cockpit specific pam stack, generally located at
<code>/etc/pam.d/cockpit</code>. By default this is configured to allow you to
login with the username and password of any local account on the system.
You can also setup a <a href="#sso">Kerberos based SSO solution</a> or
<a href="#cert-authentication">certificate/smart card authentication</a>.</p>
</div>
<div class="paragraph">
<p>You can also
<a href="https://github.com/cockpit-project/cockpit/blob/main/doc/authentication.md#actions">disable
authentication schemes</a> to enforce authentication policies, or to
suppress undesired browser GSSAPI authentication dialogs.</p>
</div>
<div class="paragraph">
<p>The web server can also be run from the
<a href="https://hub.docker.com/r/cockpit/ws/">cockpit/ws</a> container. If you are
running cockpit on a container host operating system like
<a href="https://getfedora.org/coreos/">Fedora CoreOS</a> this will be the only
supported mode. In this setup, cockpit establishes an SSH connection
from the container to the underlying host, meaning that it is up to your
SSH server to grant access. To login with a local account, <code>sshd</code> will
need to be configured to allow password based authentication.
Alternatively you can setup a <a href="#sso">Kerberos based SSO solution</a>.</p>
</div>
<div class="paragraph">
<p>Like <code>sshd</code>, cockpit can be configured to limit the number of
concurrent login attempts allowed. This is done by adding a
<code>MaxStartups</code> option to the <code>WebService</code> section of your
<code>cockpit.conf</code>. Additional connections will be dropped until
authentication succeeds or the connections are closed.</p>
</div>
</div>
<div class="sect2">
<h3 id="direct-secondary-auth">Directly logging into a secondary server without a primary session</h3>
<div class="paragraph">
<p>It is also possible to log into a secondary server without opening a
session on the primary server. This is useful if you are not actually
interested in the primary server and would only use it because you do
not have direct network access to the secondary server.</p>
</div>
<div class="paragraph">
<p>In this case, <code>cockpit-ws</code> still runs on the primary server, but the
credentials from the login screen are directly used with SSH to log into
the secondary server given in the "Connect To" field of the login
screen.</p>
</div>
<div class="paragraph">
<p>Thus, the PAM configuration and accounts on the primary server don&#8217;t
matter at all. Often, the only purpose of the primary server is to sit
on the boundary of your network and forward connections to internal
machines.</p>
</div>
<div class="paragraph">
<p>In this case, the login page will prompt you to verify unknown SSH keys.
Accepted keys will be remembered in the local storage of your browser.</p>
</div>
</div>
<div class="sect2">
<h3 id="secondary-auth">Logging into a secondary server from the primary session</h3>
<div class="paragraph">
<p>Once you have a session on the primary server, it is possible connect to
additional servers by using the host switching UI of the Cockpit Shell.
This is useful if you have direct network access to the primary server,
but not to the secondary server.</p>
</div>
<div class="paragraph">
<p>On the command line, you would log into the primary server and then use
SSH to log into the secondary one. Cockpit does just the same, and uses
SSH to log into the secondary server. Instead of running a interactive
shell there, however, it starts a <code>cockpit-bridge</code> process.</p>
</div>
<div class="paragraph">
<p><em>Warning:</em> Unlike with SSH on the command line though, this will also
load and use the Cockpit pages (i.e. JavaScript) from the remote
machine, which means that the remote machine can execute arbitrary code
on your primary and all other connected secondary machines. Hence, only
connect to <em>machines which you trust</em>.</p>
</div>
<div class="paragraph">
<p>Due to this security risk, this host switcher functionality is disabled
by default, except on long-term stable Linux distributions (Red Hat
Enterprise Linux 9, Debian 12, and Ubuntu 22.04/24.04 LTS). If you are
comfortable with the security implications, you can enable it manually
with the <code>AllowMultiHost</code> option in <code>cockpit.conf</code>.</p>
</div>
<div class="paragraph">
<p>These servers will need to be running an SSH server and be configured to
support one of the following authentication methods.</p>
</div>
<div class="sect3">
<h4 id="_password">Password</h4>
<div class="paragraph">
<p>The target server will need to have password based authentication
enabled in <code>sshd</code>.</p>
</div>
</div>
<div class="sect3">
<h4 id="_kerberos">Kerberos</h4>
<div class="paragraph">
<p>The target server will need to be a member of the same domain as the
primary server and your domain must be whitelisted in your browser. See
the <a href="#sso">SSO documentation</a> for how to set this up.</p>
</div>
</div>
<div class="sect3">
<h4 id="_public_key">Public key</h4>
<div class="paragraph">
<p>When you successfully log into the primary server, a <code>ssh-agent</code> is
started and keys are loaded into it by running <code>ssh-add</code> without any
arguments. Any passphrase prompt is answered with the password used to
log into the primary server.</p>
</div>
<div class="paragraph">
<p>Cockpit provides a user interface for loading other keys into the agent
that could not be automatically loaded.</p>
</div>
<div class="paragraph">
<p>The target server will need to have public key authentication enabled in
<code>sshd</code>, and the public key you wish to use must be present in
<code>~/.ssh/authorized_keys</code>. Cockpit has a user interface for creating
SSH keys and for authorizing them.</p>
</div>
</div>
<div class="sect3">
<h4 id="host-keys">SSH host keys</h4>
<div class="paragraph">
<p>Cockpit will prompt the user to verify unknown SSH host keys, and will
write accepted host keys into <code>~/.ssh/known_hosts</code>.</p>
</div>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="sso">Single Sign On</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Cockpit can use Kerberos for Single Sign On authentication, where users
are automatically authenticated if they have a valid Kerberos ticket.</p>
</div>
<div class="sect2">
<h3 id="sso-server">Server Requirements</h3>
<div class="paragraph">
<p>To authenticate users, the server that Cockpit is running on must be
joined to a domain. This can usually be accomplished using the
<a href="https://freedesktop.org/software/realmd/docs/realm.html"><code>realm join example.com</code></a>
command.</p>
</div>
<div class="paragraph">
<p>The domain must be resolvable by DNS. For instance, the SRV records of
the kerberos server should be resolvable:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ host -t SRV  _kerberos._udp.example.com
_kerberos._udp.example.com has SRV record 0 100 88 dc.example.com</pre>
</div>
</div>
<div class="paragraph">
<p>The server running Cockpit should have a fully qualified name that ends
with the domain name.</p>
</div>
<div class="paragraph">
<p>There must be a valid Kerberos host key for the server in the
<code>/etc/krb5.keytab</code> file. Alternatively, if you would like to use a
different keytab, you can do so by placing it in
<code>/etc/cockpit/krb5.keytab</code>, or below <code>$XDG_CONFIG_DIRS</code> if set (see
<a href="./cockpit.conf.5.html">cockpit.conf</a>). It may be necessary to create
a kerberos service principal and update the keytab if it is not present.
Depending on your domain type different service names are required:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Active Directory</dt>
<dd>
<p><code>HOST/server.example.com@EXAMPLE.COM</code></p>
</dd>
<dt class="hdlist1">IPA and MIT</dt>
<dd>
<p><code>HTTP/server.example.com@EXAMPLE.COM</code></p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>When joining an IPA domain with Cockpit and the <code>ipa</code> command line
tool is available, both the service principal name and a
<code>/etc/cockpit/krb5.keytab</code> get created automatically, so that Kerberos
based single sign on into Cockpit works out of the box. If you want/need
to do this by hand or in a script, first create or modify the <code>HTTP/</code>
service principal:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo ipa service-add --ok-as-delegate=true --ok-to-auth-as-delegate=true \
    HTTP/server.example.com@EXAMPLE.COM
# or, if it already exists, just enable delegation:
$ sudo ipa service-mod --ok-as-delegate=true --ok-to-auth-as-delegate=true \
    HTTP/server.example.com@EXAMPLE.COM</pre>
</div>
</div>
<div class="paragraph">
<p>Then generate a key for that principal:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo ipa-getkeytab -p HTTP/server.example.com@EXAMPLE.COM -k /etc/cockpit/krb5.keytab</pre>
</div>
</div>
<div class="paragraph">
<p>The following command can be used to list the
<code>/etc/cockpit/krb5.keytab</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo klist -k /etc/cockpit/krb5.keytab</pre>
</div>
</div>
<div class="paragraph">
<p>Lastly accounts from the domain must be resolvable to unix accounts on
the server running Cockpit. For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ getent passwd user@example.com
user@example.com:*:381001109:381000513:User Name:/home/user:/bin/sh</pre>
</div>
</div>
<div class="paragraph">
<p>If you wish to delegate your kerberos credentials to Cockpit, and allow
Cockpit to then connect to other machines using those credentials, you
should enable delegation for the hosts running Cockpit, and in some
cases the <code>HTTP</code> service as well. When joining an IPA domain, this is
enabled by default.</p>
</div>
<div class="paragraph">
<p>Domain admins (usually the <code>admins@example.com</code> group) should normally
also be able to administer any joined machine. Enable sudo access for
that group with the following command on the IPA server, for version
4.7.1 and later:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>ipa-advise enable-admins-sudo | sh -ex</pre>
</div>
</div>
<div class="paragraph">
<p>On earlier FreeIPA versions, run these commands instead, as a domain
admin on any joined machine:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>ipa sudorule-add --hostcat=all --cmdcat=all All
ipa sudorule-add-user --groups=admins All</pre>
</div>
</div>
<div class="paragraph">
<p>Note that this does not change security properties; domain admins can
give this privilege to themselves, so it is safe to enable by default.</p>
</div>
</div>
<div class="sect2">
<h3 id="sso-client">Client Requirements</h3>
<div class="paragraph">
<p>The client side, where your web browser is running, should have a valid
kerberos ticket in the current user session. A command like this will
get one:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ kinit user@EXAMPLE.COM
Password for user@EXAMPLE.COM:</pre>
</div>
</div>
<div class="paragraph">
<p>In addition your browser must be usually be configured to allow kerberos
authentication for the domain.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Mozilla Firefox</dt>
<dd>
<p>Go to <code>about:config</code> and set the
<code>network.negotiate-auth.trusted-uris</code> setting to your domain name
preceded by a dot, ie: <code>.example.com</code></p>
</dd>
<dt class="hdlist1">Google Chrome</dt>
<dd>
<p>On Linux: create the file
<code>/etc/opt/chrome/policies/managed/example-com.json</code> with the
contents:</p>
</dd>
<dt class="hdlist1"></dt>
</dl>
</div>
<div class="literalblock">
<div class="content">
<pre>{
  "AuthServerWhitelist": "*example.com"
}</pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"></dt>
<dd>
<p>and restart the browser. On other platforms, exit your browser
completely, and start it with a command line like this:
<code>google-chrome --auth-server-whitelist=*example.com</code></p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Use a fully qualified server name (with the domain name at the end) to
access Cockpit in your web browser.</p>
</div>
<div class="paragraph">
<p>If you wish to connect from one server to another in Cockpit using
kerberos SSO, then you have to explicitly enable all sorts of things.
For starters, make sure that delegated credentials are allowed by your
domain (see above). Next when requesting your kerberos ticket make sure
that forwardable tickets are requested:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ kinit -f user@EXAMPLE.COM
Password for user@EXAMPLE.COM:</pre>
</div>
</div>
<div class="paragraph">
<p>Make sure that the forwardable flag <code>F</code> is present in your ticket:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ klist -f
Ticket cache: KEYRING:persistent:1000:1000
Default principal: user@EXAMPLE.COM

Valid starting       Expires              Service principal
18.03.2017 05:39:23  19.03.2017 05:39:20  krbtgt/EXAMPLE.COM@EXAMPLE.COM
    Flags: FIA</pre>
</div>
</div>
<div class="paragraph">
<p>Lastly configure your browser to allow delegated, forwardable kerberos
credentials to be sent to Cockpit:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Mozilla Firefox</dt>
<dd>
<p>Go to <code>about:config</code> and set the
<code>network.negotiate-auth.delegation-uris</code> setting to your domain name
preceded by a dot, ie: <code>.example.com</code></p>
</dd>
<dt class="hdlist1">Google Chrome</dt>
<dd>
<p>On Linux: create the file
<code>/etc/opt/chrome/policies/managed/example-com.json</code> with the
contents:</p>
</dd>
<dt class="hdlist1"></dt>
</dl>
</div>
<div class="literalblock">
<div class="content">
<pre>{
  "AuthServerWhitelist": "*example.com",
  "AuthNegotiateDelegateWhitelist": "*example.com"
}</pre>
</div>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"></dt>
<dd>
<p>and restart the browser. On other platforms, exit your browser
completely, and start it with a command line like this:
<code>google-chrome --auth-server-whitelist=*example.com --auth-negotiate-delegate-whitelist=*example.com</code></p>
</dd>
</dl>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="cert-authentication">Certificate/smart card authentication</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Cockpit can use TLS client certificates for authenticating users.
Commonly these are provided by a smart card, but it&#8217;s equally possible
to import certificates directly into the web browser.</p>
</div>
<div class="paragraph">
<p>This requires the host to be in an Identity Management domain like
<a href="https://www.freeipa.org">FreeIPA</a> or
<a href="https://en.wikipedia.org/wiki/Active_Directory">Active Directory</a>, which
can associate certificates to users.</p>
</div>
<div class="paragraph">
<p>To authenticate users from a Identity Management domain, the server that
Cockpit is running on must be joined to that domain. See the
<a href="#sso-server">SSO server requirements</a> for details.</p>
</div>
<div class="sect2">
<h3 id="certauth-server-cert-generation">User certificate generation</h3>
<div class="paragraph">
<p>Generating the certificates for users is usually done with a certificate
management system like <a href="https://pagure.io/certmonger">certmonger</a> or
<a href="https://www.freeipa.org/page/PKI">FreeIPA</a>, which are not documented
here. This command generates a simple key and certificate request for
the "alice" user:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>openssl req -new -newkey rsa:2048 -days 365 \
    -keyout alice.key -out alice.csr -subj "/CN=alice"</pre>
</div>
</div>
<div class="paragraph">
<p>Now get this certificate request signed by the Certificate Authority of
your Identity Management domain, to get a PEM certificate. Browsers and
smart cart utilities accept PKCS#12 format for importing/transfer, so
convert the certificate/key pair; it will ask for and protect it with a
transfer password:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>openssl pkcs12 -export -in alice.pem -inkey alice.key -out alice.p12</pre>
</div>
</div>
<div class="paragraph">
<p>Don&#8217;t forget to clean up the key file when you do not need it any more:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>shred -u alice.key</pre>
</div>
</div>
<div class="paragraph">
<p>You can now import <code>alice.p12</code> directly into your browser, with giving
the transfer password set above. Or
<a href="https://linux.die.net/man/1/pkcs15-init">put the certificate onto a smart
card</a>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>pkcs15-init --store-private-key alice.p12 --format pkcs12 --auth-id 01</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="certauth-server-ipa">Certificate mapping with FreeIPA</h3>
<div class="paragraph">
<p>The recommended method to sign a user certificate request and associate
it to a user is <code>ipa cert-request</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>ipa cert-request alice.csr --principal=alice --certificate-out=alice.pem</pre>
</div>
</div>
<div class="paragraph">
<p>Alternatively, if you are using a different CA, you can use
<code>ipa user-add-cert</code> to associate the signed certificate to the user.
This expects PEM format, but without the <code>-----BEGIN</code>/<code>-----END</code>
markers:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>ipa user-add-cert alice --certificate="$(grep -v ^---- alice.pem)"</pre>
</div>
</div>
<div class="paragraph">
<p>See the
<a href="https://www.freeipa.org/page/V4/User_Certificates#Feature_Management">FreeIPA
User Certificates documentation</a> for details.</p>
</div>
</div>
<div class="sect2">
<h3 id="certauth-server-ms-ad">Certificate mapping with Microsoft Active Directory</h3>
<div class="paragraph">
<p>The domain user certificates get imported into the
<code>userCertificate;binary</code> LDAP attribute. The following commands
convert the PEM certificate into binary DER form, create an
<a href="https://ldap.com/ldif-the-ldap-data-interchange-format/">LDIF</a> file and
apply it to the LDAP server running on the domain controller
"dc.example.com":</p>
</div>
<div class="literalblock">
<div class="content">
<pre>openssl x509 -outform der -in alice.pem -out alice.der

cat &lt;&lt;EOF &gt; alice.ldif
version: 1
dn: cn=alice,ou=users,ou=YOUR_NETBIOS_NAME,dc=example,dc=com
changetype: modify
add: userCertificate;binary
userCertificate;binary:&lt; file://$(pwd)/alice.der
EOF

ldapmodify -H ldap://dc.example.com -f alice.ldif</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="certauth-server-samba-ad">Certificate mapping with Samba Active Directory</h3>
<div class="paragraph">
<p>At least some versions of <a href="https://www.samba.org/">Samba</a> do not support
the <code>userCertificate;binary</code> LDAP attribute, so the import has to
happen in base64 PEM form into the textual <code>userCertificate</code> attribute
instead. Also, Samba uses a slightly different user hierarchy:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cat &lt;&lt;EOF &gt; alice.ldif
version: 1
dn: cn=alice,cn=users,dc=example,dc=com
changetype: modify
add: userCertificate
userCertificate: $(grep -v ^---- alice.pem | tr -d '\n')
EOF

ldapmodify -H ldap://dc.example.com  -f alice.ldif</pre>
</div>
</div>
<div class="paragraph">
<p>As <code>userCertificate</code> is a text instead of binary field, you need to
set up a
<a href="https://www.mankier.com/5/sssd.conf#Certificate_Mapping_Section">certificate
mapping rule</a> in <code>sssd.conf(5)</code> in a <code>[certmap/domain/rulename]</code>
section, for example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[certmap/example.com/adcerts]
# we match full certificates, so it is not important to check anything here
matchrule = &lt;KU&gt;digitalSignature
maprule = LDAP:(userCertificate={cert!base64})</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="certauth-server-cockpitconf">Cockpit web server configuration</h3>
<div class="paragraph">
<p>Set the trusted Certificate Authority of your user certificates in
<code>sssd</code>, either by copying the CA PEM file to
<code>/etc/sssd/pki/sssd_auth_ca_db.pem</code> or setting the
<a href="https://www.mankier.com/5/sssd.conf#Services_Sections-PAM_configuration_options"><code>pam_cert_db_path</code></a>
configuration option to the path of the CA. If you use FreeIPA and its
CA:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cp /etc/ipa/ca.crt /etc/sssd/pki/sssd_auth_ca_db.pem</pre>
</div>
</div>
<div class="paragraph">
<p>Certificate authentication needs to be enabled in
<a href="./cockpit.conf.5.html">cockpit.conf</a> explicitly:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[WebService]
ClientCertAuthentication = yes</pre>
</div>
</div>
<div class="paragraph">
<p>When enabling this mode,
<a href="https://github.com/cockpit-project/cockpit/blob/main/doc/authentication.md">other
authentication types</a> commonly get disabled, so that <em>only</em> client
certificate authentication will be accepted. By default, after a failed
certificate authentication attempt, Cockpit&#8217;s normal login page will
appear and permit other login types such as <code>basic</code> (passwords) or
<code>negotiate</code> (Kerberos). For example, password authentication gets
disabled with:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>[basic]
action = none</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="certauth-server-resourcelimits">Cockpit web server resource limits</h3>
<div class="paragraph">
<p>When using certificate authentication, all requests with a particular
certificate will be handled by a separate and isolated instance of the
<a href="./cockpit-ws.8.html">cockpit-ws</a> web server. This protects against
possible vulnerabilities in the web server and prevents an attacker from
impersonating another user. However, this introduces a potential Denial
of Service: Some remote attacker could create a large number of
certificates and send a large number of http requests to Cockpit with
these.</p>
</div>
<div class="paragraph">
<p>To mitigate that, all <code>cockpit-ws</code> instances run in a
<code>system-cockpithttps.slice</code>
<a href="https://www.freedesktop.org/software/systemd/man/systemd.slice.html">systemd
slice unit</a> which
<a href="https://www.freedesktop.org/software/systemd/man/systemd.resource-control.html">limits
the collective resources</a> of these web server instances: by default,
this slice sets a limit of 200 threads (roughly 100 instances of
<code>cockpit-ws</code>&#8201;&#8212;&#8201;in other words, a maximum of 100 parallel user
sessions with different certificates) and a 75% (soft)/90% (hard) memory
limit.</p>
</div>
<div class="paragraph">
<p>You are welcome to adjust these limits to your need through a
<a href="https://www.freedesktop.org/software/systemd/man/systemd.unit.html">drop-in</a>.
For example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># systemctl edit system-cockpithttps.slice

[Slice]
# change existing value
TasksMax=100
# add new restriction
CPUQuota=30%</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="certauth-forwarding">Authentication to other services like sudo and ssh</h3>
<div class="paragraph">
<p>Once you logged into Cockpit with a certificate, you likely need to
switch to administrative mode (root privileges through sudo), or connect
to remote machines through SSH. If your user account has a password,
that can be used for authenticating to sudo or ssh as usual.</p>
</div>
<div class="paragraph">
<p><em>Supported with FreeIPA only:</em> As an alternative to password
authentication, you can also declare the initial Cockpit certificate
authentication as trusted for authenticating to SSH, sudo, or other
services. For that purpose, Cockpit automatically creates an
<a href="https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-sfu/bde93b0e-f3c9-4ddf-9f44-e1453be7af5a">S4U2Proxy
Kerberos ticket</a> in the user session:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ klist
Ticket cache: FILE:/run/user/1894000001/cockpit-session-3692.ccache
Default principal: user@EXAMPLE.COM

Valid starting     Expires            Service principal
07/30/21 09:19:06  07/31/21 09:19:06  HTTP/myhost.example.com@EXAMPLE.COM
07/30/21 09:19:06  07/31/21 09:19:06  krbtgt/EXAMPLE.COM@EXAMPLE.COM
    for client HTTP/myhost.example.com@EXAMPLE.COM</pre>
</div>
</div>
<div class="paragraph">
<p>You can set up
<a href="https://www.freeipa.org/page/V4/Service_Constraint_Delegation">constrained
delegation rules</a> to enumerate which hosts (including its own) that
ticket is trusted to access. For example, if the cockpit session runs on
host <code>myhost.example.com</code> and should be trusted to access its own host
(through sudo) and another host <code>remote.example.com</code> (through ssh),
create a delegation like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre># a list of target machines which can be accessed by a particular rule
ipa servicedelegationtarget-add cockpit-target
ipa servicedelegationtarget-add-member cockpit-target \
  --principals=host/myhost.example.com@EXAMPLE.COM \
  --principals=host/remote.example.com@EXAMPLE.COM

# allow cockpit sessions (HTTP/ principal) to access that host list
ipa servicedelegationrule-add cockpit-delegation
ipa servicedelegationrule-add-member cockpit-delegation \
  --principals=HTTP/myhost.example.com@EXAMPLE.COM
ipa servicedelegationrule-add-target cockpit-delegation \
  --servicedelegationtargets=cockpit-target</pre>
</div>
</div>
<div class="paragraph">
<p>In addition, you need to enable GSS (Kerberos) authentication in the
corresponding services.</p>
</div>
<div class="ulist">
<ul>
<li>
<p>For SSH, enable <code>GSSAPIAuthentication yes</code> in
<a href="https://linux.die.net/man/5/sshd_config">/etc/ssh/sshd_config</a>.</p>
</li>
<li>
<p>For sudo, enable <code>pam_sss_gss</code> as described in the
<a href="https://www.mankier.com/8/pam_sss_gss">manpage</a>: In
<code>/etc/sssd/sssd.conf</code>: Add an entry for your domain:</p>
<div class="literalblock">
<div class="content">
<pre>[domain/example.com]
pam_gssapi_services = sudo, sudo-i</pre>
</div>
</div>
<div class="paragraph">
<p>In <code>/etc/pam.d/sudo</code>, enable the module in the first line:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>auth sufficient pam_sss_gss.so</pre>
</div>
</div>
</li>
</ul>
</div>
<div class="paragraph">
<p><em>Caveat:</em> The delegated S4U ticket is not yet forwarded to remote SSH
hosts when connecting to them from Cockpit, so authenticating to sudo on
the remote host with that ticket does not work. This will be provided in
a future version.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="privileges">Privileges and Permissions</h2>
<div class="sectionbody">
<div class="paragraph">
<p>When a user is logged into Cockpit, they are logged into a normal
session that has exactly the same privileges as if they logged in via
SSH or on the console.</p>
</div>
<div class="paragraph">
<p>However, Cockpit will usually try to escalate the privileges of the user
using <a href="https://www.freedesktop.org/wiki/Software/polkit/">Policy Kit</a> or
<a href="https://www.sudo.ws/">sudo</a>. If the user is able to escalate privileges
from the command line by typing in their password again (or without
typing in any password), then Cockpit will be able to escalate the
privileges of the session to "root" immediately upon login.</p>
</div>
<div class="paragraph">
<p>The user can change the privileges of a session from within that
session, via the "Administrative access" indicator in the top bar. From
that indicator, the user can drop "root" privileges and regain them. On
the next login, Cockpit will give the session the same privileges.</p>
</div>
<div class="paragraph">
<p>Usually a user needs to be in the <code>wheel</code> Unix user group for the user
to be able to escalate privileges in this way. However both Policy Kit
and sudo may be configured to use other criteria.</p>
</div>
<div class="sect2">
<h3 id="privileges-polkit">Customizing Polkit Privileges</h3>
<div class="paragraph">
<p>Services like
<a href="https://www.freedesktop.org/wiki/Software/systemd/">systemd</a> and
<a href="https://wiki.gnome.org/Projects/NetworkManager">NetworkManager</a> use
<a href="https://www.freedesktop.org/wiki/Software/polkit/">Polkit</a> to validate
and escalate privileges. It is possible to customize these rules with
files in <code>/etc/polkit-1/rules.d</code>.</p>
</div>
<div class="paragraph">
<p>Polkit rules files are
<a href="https://www.freedesktop.org/software/polkit/docs/latest/polkit.8.html">javascript
with specific methods and objects</a>. For example, placing the following
polkit rule to <code>/etc/polkit-1/rules.d/10-operators.rule</code> allows all
users in the <code>operators</code> group to start, stop, restart and otherwise
manage systemd services:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>polkit.addRule(function(action, subject) {
    if (action.id == "org.freedesktop.systemd1.manage-units") {
        if (subject.isInGroup("operators")) {
            return polkit.Result.YES;
        }
    }
});</pre>
</div>
</div>
<div class="paragraph">
<p>In order to allow a certain group to perform any administrative action
you could add a rule like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>polkit.addAdminRule(function(action, subject) {
    return ["unix-group:operators"];
});</pre>
</div>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
Last updated 2026-01-28 11:12:25 UTC
</div>
</div>
</body>
</html>