File: index.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 (7887 lines) | stat: -rw-r--r-- 301,613 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>Cockpit documentation</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 class="article toc2 toc-left">
<div id="header">
<h1>Cockpit documentation</h1>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#guide">Deployment Guide</a>
<ul class="sectlevel2">
<li><a href="#cockpit-manual">Manual pages</a>
<ul class="sectlevel3">
<li><a href="#_cockpit1">cockpit(1)</a></li>
<li><a href="#_cockpit_conf5">cockpit.conf(5)</a></li>
<li><a href="#_cockpit_ws8">cockpit-ws(8)</a></li>
<li><a href="#_cockpit_tls8">cockpit-tls(8)</a></li>
<li><a href="#_cockpit_desktop1">cockpit-desktop(1)</a></li>
<li><a href="#_cockpit_bridge1">cockpit-bridge(1)</a></li>
<li><a href="#_pam_ssh_add8">pam_ssh_add(8)</a></li>
</ul>
</li>
<li><a href="#https">SSL/TLS Usage</a>
<ul class="sectlevel3">
<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="sectlevel3">
<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="sectlevel3">
<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="sectlevel3">
<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></li>
</ul>
</li>
<li><a href="#sso">Single Sign On</a>
<ul class="sectlevel3">
<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="sectlevel3">
<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="sectlevel3">
<li><a href="#privileges-polkit">Customizing Polkit Privileges</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#features">Feature Internals</a>
<ul class="sectlevel2">
<li><a href="#feature-systemd">systemd</a></li>
<li><a href="#feature-journal">Journal</a></li>
<li><a href="#feature-networkmanager">NetworkManager</a></li>
<li><a href="#feature-firewall">Firewall</a></li>
<li><a href="#feature-storaged">storaged</a></li>
<li><a href="#feature-users">User Tools</a></li>
<li><a href="#feature-realmd">realmd</a></li>
<li><a href="#feature-terminal">Terminal</a></li>
<li><a href="#feature-pcp">PCP Metrics</a></li>
<li><a href="#feature-machines">Multiple Machines</a></li>
<li><a href="#feature-selinux">SELinux Policy</a></li>
<li><a href="#feature-tuned">Tuned Profiles</a></li>
<li><a href="#feature-sosreport">SOS Report</a></li>
<li><a href="#feature-packagekit">Package Updates</a></li>
</ul>
</li>
<li><a href="#development">Developer Guide</a>
<ul class="sectlevel2">
<li><a href="#embedding">Embedding and Integrating Cockpit</a>
<ul class="sectlevel3">
<li><a href="#embedding-full">Embedding the Cockpit Interface</a></li>
<li><a href="#embedding-components">Integrating Cockpit Components into Web Applications</a></li>
<li><a href="#embedding-deep">Deep Integration</a></li>
<li><a href="#embedding-cors">Pinging Cockpit</a></li>
</ul>
</li>
<li><a href="#packages">Cockpit Packages</a>
<ul class="sectlevel3">
<li><a href="#package-layout">Layout of Package Files</a></li>
<li><a href="#_package_manifest">Package Manifest</a></li>
<li><a href="#package-manifest-override">Manifest overrides</a></li>
<li><a href="#package-links">Package Links and Paths</a></li>
<li><a href="#package-minified">Content Negotiation</a></li>
<li><a href="#package-api">Using Cockpit API</a></li>
<li><a href="#package-bridges">Bridges for specific tasks</a></li>
<li><a href="#package-replace">Replacing an existing package</a></li>
</ul>
</li>
<li><a href="#urls">Cockpit URLs</a>
<ul class="sectlevel3">
<li><a href="#urls-components">Component URLs</a></li>
<li><a href="#urls-visible">Visible URLs</a></li>
</ul>
</li>
<li><a href="#_api_base1">API: base1</a>
<ul class="sectlevel3">
<li><a href="#_cockpit_js">cockpit.js</a></li>
<li><a href="#_cockpit_js_object_caching">cockpit.js: Object Caching</a></li>
<li><a href="#_cockpit_js_raw_channels">cockpit.js: Raw Channels</a></li>
<li><a href="#_cockpit_js_dbus_client">cockpit.js: DBus Client</a></li>
<li><a href="#_cockpit_js_errors">cockpit.js: Errors</a></li>
<li><a href="#_cockpit_js_file_access">cockpit.js: File Access</a></li>
<li><a href="#_cockpit_js_http_client">cockpit.js: HTTP Client</a></li>
<li><a href="#_cockpit_js_localization">cockpit.js: Localization</a></li>
<li><a href="#_cockpit_js_page_location_and_jumping">cockpit.js: Page Location and Jumping</a></li>
<li><a href="#_cockpit_js_user_session">cockpit.js: User Session</a></li>
<li><a href="#_cockpit_js_manifests">cockpit.js: Manifests</a></li>
<li><a href="#_cockpit_js_metrics">cockpit.js: Metrics</a></li>
<li><a href="#_cockpit_js_series_data">cockpit.js: Series Data</a></li>
<li><a href="#_cockpit_js_spawning_processes">cockpit.js: Spawning Processes</a></li>
<li><a href="#_cockpit_js_utilities">cockpit.js: Utilities</a></li>
</ul>
</li>
<li><a href="#_api_shell">API: shell</a>
<ul class="sectlevel3">
<li><a href="#_index_html">index.html</a></li>
</ul>
</li>
<li><a href="#_api_system">API: system</a>
<ul class="sectlevel3">
<li><a href="#_logs_html">logs.html</a></li>
<li><a href="#_terminal_html">terminal.html</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="guide">Deployment Guide</h2>
<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 class="sect2">
<h3 id="cockpit-manual">Manual pages</h3>
<div class="sect3">
<h4 id="_cockpit1">cockpit(1)</h4>
<div class="sect4">
<h5 id="_name">Name</h5>
<div class="paragraph">
<p>cockpit - Cockpit</p>
</div>
</div>
<div class="sect4">
<h5 id="_description">Description</h5>
<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="sect4">
<h5 id="_components">Components</h5>
<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="sect4">
<h5 id="_bugs">Bugs</h5>
<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="sect4">
<h5 id="_author">Author</h5>
<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="sect4">
<h5 id="_see_also">See also</h5>
<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="sect3">
<h4 id="_cockpit_conf5">cockpit.conf(5)</h4>
<div class="sect4">
<h5 id="_name_2">Name</h5>
<div class="paragraph">
<p>cockpit.conf - Cockpit configuration file</p>
</div>
</div>
<div class="sect4">
<h5 id="_description_2">Description</h5>
<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="sect4">
<h5 id="_webservice">WebService</h5>
<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="sect4">
<h5 id="_log">Log</h5>
<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="sect4">
<h5 id="_oauth">OAuth</h5>
<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="sect4">
<h5 id="_session">Session</h5>
<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="sect4">
<h5 id="_bugs_2">Bugs</h5>
<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="sect4">
<h5 id="_author_2">Author</h5>
<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="sect4">
<h5 id="_see_also_2">See also</h5>
<div class="paragraph">
<p><strong>cockpit-ws(8)</strong>, <strong>cockpit-tls(8)</strong></p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_ws8">cockpit-ws(8)</h4>
<div class="sect4">
<h5 id="_name_3">Name</h5>
<div class="paragraph">
<p>cockpit-ws - Cockpit web service</p>
</div>
</div>
<div class="sect4">
<h5 id="_synopsis">Synopsis</h5>
<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="sect4">
<h5 id="_description_3">Description</h5>
<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="sect4">
<h5 id="_transport_security">Transport security</h5>
<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="sect4">
<h5 id="_timeout">Timeout</h5>
<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="sect4">
<h5 id="_options">Options</h5>
<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="sect4">
<h5 id="_environment">Environment</h5>
<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="sect4">
<h5 id="_bugs_3">Bugs</h5>
<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="sect4">
<h5 id="_author_3">Author</h5>
<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="sect4">
<h5 id="_see_also_3">See also</h5>
<div class="paragraph">
<p><strong>cockpit-tls(8)</strong> , <strong>cockpit.conf(5)</strong> , <strong>systemd(1)</strong></p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_tls8">cockpit-tls(8)</h4>
<div class="sect4">
<h5 id="_name_4">Name</h5>
<div class="paragraph">
<p>cockpit-tls - TLS proxy for Cockpit web service</p>
</div>
</div>
<div class="sect4">
<h5 id="_synopsis_2">Synopsis</h5>
<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="sect4">
<h5 id="_description_4">Description</h5>
<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="sect4">
<h5 id="_transport_security_2">Transport security</h5>
<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="sect4">
<h5 id="_options_2">Options</h5>
<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="sect4">
<h5 id="_environment_2">Environment</h5>
<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="sect4">
<h5 id="_bugs_4">Bugs</h5>
<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="sect4">
<h5 id="_author_4">Author</h5>
<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="sect4">
<h5 id="_see_also_4">See also</h5>
<div class="paragraph">
<p><strong>cockpit-ws(8)</strong> , <strong>cockpit.conf(5)</strong> , <strong>systemd(1)</strong></p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_desktop1">cockpit-desktop(1)</h4>
<div class="sect4">
<h5 id="_name_5">Name</h5>
<div class="paragraph">
<p>cockpit-desktop - Cockpit Desktop integration</p>
</div>
</div>
<div class="sect4">
<h5 id="_synopsis_3">Synopsis</h5>
<div class="paragraph">
<p><strong>cockpit-desktop</strong> <em>URLPATH</em> [<em>SSH_HOST</em>]</p>
</div>
</div>
<div class="sect4">
<h5 id="_description_5">Description</h5>
<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="sect4">
<h5 id="_environment_3">Environment</h5>
<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="sect4">
<h5 id="_bugs_5">Bugs</h5>
<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="sect4">
<h5 id="_author_5">Author</h5>
<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="sect4">
<h5 id="_see_also_5">See also</h5>
<div class="paragraph">
<p><strong>cockpit-ws(8)</strong>, <strong>cockpit-bridge(1)</strong></p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_bridge1">cockpit-bridge(1)</h4>
<div class="sect4">
<h5 id="_name_6">Name</h5>
<div class="paragraph">
<p>cockpit-bridge - Cockpit Host Bridge</p>
</div>
</div>
<div class="sect4">
<h5 id="_synopsis_4">Synopsis</h5>
<div class="paragraph">
<p><strong>cockpit-bridge</strong> [<strong>--help</strong>] [<strong>--packages</strong>]</p>
</div>
</div>
<div class="sect4">
<h5 id="_description_6">Description</h5>
<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="sect4">
<h5 id="_options_3">Options</h5>
<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="sect4">
<h5 id="_bugs_6">Bugs</h5>
<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="sect4">
<h5 id="_author_6">Author</h5>
<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="sect4">
<h5 id="_see_also_6">See also</h5>
<div class="paragraph">
<p><strong>cockpit-ws(8)</strong></p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_pam_ssh_add8">pam_ssh_add(8)</h4>
<div class="sect4">
<h5 id="_name_7">Name</h5>
<div class="paragraph">
<p>pam_ssh_add - PAM module to auto load ssh keys into an agent</p>
</div>
</div>
<div class="sect4">
<h5 id="_description_7">Description</h5>
<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="sect4">
<h5 id="_options_4">Options</h5>
<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="sect4">
<h5 id="_examples">Examples</h5>
<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="sect4">
<h5 id="_bugs_7">Bugs</h5>
<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="sect4">
<h5 id="_author_7">Author</h5>
<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 class="sect2">
<h3 id="https">SSL/TLS Usage</h3>
<div class="paragraph">
<p>Cockpit usually requires that web browsers communicate with it using
HTTPS, for security reasons.</p>
</div>
<div class="sect3">
<h4 id="https-required">HTTPS Requirement</h4>
<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="sect3">
<h4 id="https-certificates">Certificates</h4>
<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 class="sect2">
<h3 id="listen">TCP Port and Address</h3>
<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="sect3">
<h4 id="listen-systemd">Cockpit systemd Socket</h4>
<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="sect3">
<h4 id="listen-selinux">SELinux Port</h4>
<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="sect3">
<h4 id="listen-firewalld">Firewalld Port</h4>
<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 class="sect2">
<h3 id="startup">Start up</h3>
<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="sect3">
<h4 id="startup-shutdown">Process exit</h4>
<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="sect3">
<h4 id="startup-boot">Boot start up</h4>
<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 class="sect2">
<h3 id="multi-host">Managing multiple hosts at the same time</h3>
<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 class="sect2">
<h3 id="authentication">Cockpit Authentication</h3>
<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="sect3">
<h4 id="initial-auth">Directly logging into the primary server</h4>
<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="sect3">
<h4 id="direct-secondary-auth">Directly logging into a secondary server without a primary session</h4>
<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="sect3">
<h4 id="secondary-auth">Logging into a secondary server from the primary session</h4>
<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="sect4">
<h5 id="_password">Password</h5>
<div class="paragraph">
<p>The target server will need to have password based authentication
enabled in <code>sshd</code>.</p>
</div>
</div>
<div class="sect4">
<h5 id="_kerberos">Kerberos</h5>
<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="sect4">
<h5 id="_public_key">Public key</h5>
<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="sect4">
<h5 id="host-keys">SSH host keys</h5>
<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 class="sect2">
<h3 id="sso">Single Sign On</h3>
<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="sect3">
<h4 id="sso-server">Server Requirements</h4>
<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="sect3">
<h4 id="sso-client">Client Requirements</h4>
<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 class="sect2">
<h3 id="cert-authentication">Certificate/smart card authentication</h3>
<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="sect3">
<h4 id="certauth-server-cert-generation">User certificate generation</h4>
<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="sect3">
<h4 id="certauth-server-ipa">Certificate mapping with FreeIPA</h4>
<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="sect3">
<h4 id="certauth-server-ms-ad">Certificate mapping with Microsoft Active Directory</h4>
<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="sect3">
<h4 id="certauth-server-samba-ad">Certificate mapping with Samba Active Directory</h4>
<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="sect3">
<h4 id="certauth-server-cockpitconf">Cockpit web server configuration</h4>
<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="sect3">
<h4 id="certauth-server-resourcelimits">Cockpit web server resource limits</h4>
<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="sect3">
<h4 id="certauth-forwarding">Authentication to other services like sudo and ssh</h4>
<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 class="sect2">
<h3 id="privileges">Privileges and Permissions</h3>
<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="sect3">
<h4 id="privileges-polkit">Customizing Polkit Privileges</h4>
<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 class="sect1">
<h2 id="features">Feature Internals</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="feature-systemd">systemd</h3>
<div class="paragraph">
<p>Cockpit uses <a href="https://www.freedesktop.org/wiki/Software/systemd/">systemd</a>
and the DBus APIs it provides to configure and monitor core aspects of
the system. Use of alternate system APIs are not currently implemented.</p>
</div>
<div class="paragraph">
<p>For non root users, systemd controls access to its APIs via
<a href="#privileges">Policy Kit</a> and a user logged into Cockpit will have
the same permissions as they do from the command line.</p>
</div>
<div class="paragraph">
<p>Cockpit retrieves information about the host and changes the hostname
via the <code>hostnamed</code> daemon. To perform similar tasks from the command
line use the
<a href="https://www.freedesktop.org/software/systemd/man/hostnamectl.html"><code>hostnamectl</code></a>
command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ hostnamectl
   Static hostname: pink.example.com
   Pretty hostname: Pink
         Icon name: computer-desktop
           Chassis: desktop
        Machine ID: ef00b79be229463cbb844c3e715de96c
           Boot ID: 934983d64d34465cb5a8383b5a89ad8c
  Operating System: Fedora 22 (Twenty Two)
       CPE OS Name: cpe:/o:fedoraproject:fedora:22
            Kernel: Linux 4.0.4-301.fc22.x86_64
      Architecture: x86-64</pre>
</div>
</div>
<div class="paragraph">
<p>Cockpit configures the system time and time zone via the <code>timedated</code>
daemon. To perform similar tasks from the command line use the
<a href="https://www.freedesktop.org/software/systemd/man/timedatectl.html"><code>timedatectl</code></a>
command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ timedatectl list-timezones
Africa/Abidjan
Africa/Accra
Africa/Addis_Ababa
Africa/Algiers
...</pre>
</div>
</div>
<div class="paragraph">
<p>Cockpit can manage the list of NTP servers used by <code>systemd-timesyncd</code>
by putting its own file into <code>/etc/systemd/timesyncd.conf.d/</code>. Note
that <code>systemd-timesyncd</code> is not always enabled, depending on the
configuration of the machine. In that case, Cockpit disabled the UI for
managing the list of NTP servers. In some cases use of <code>ntpd</code> can
cause the <code>timedated</code> daemon to behave inconsistently with regards to
time synchronization.</p>
</div>
<div class="paragraph">
<p>Cockpit reboots or powers down the machine by using the
<a href="https://www.freedesktop.org/software/systemd/man/shutdown.html"><code>shutdown</code></a>
command. To perform similar tasks from the command line, run it
directly:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo shutdown +15
Shutdown scheduled for Sa 2015-09-26 15:49:40 CEST, use 'shutdown -c' to cancel.</pre>
</div>
</div>
<div class="paragraph">
<p>Cockpit manages system services and sockets via systemd. To perform
similar tasks from the command line use the
<a href="https://www.freedesktop.org/software/systemd/man/systemctl.html"><code>systemctl</code></a>
command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ systemctl status cockpit
● cockpit.service - Cockpit Web Service
   Loaded: loaded (/usr/lib/systemd/system/cockpit.service; static; vendor preset: disabled)
  Drop-In: /etc/systemd/system/cockpit.service.d
           └─debug.conf
   Active: active (running) since Sa 2015-09-26 13:28:02 CEST; 2h 7min ago
     Docs: man:cockpit-ws(8)
 Main PID: 6957 (cockpit-ws)
   Memory: 1.8M
   CGroup: /system.slice/cockpit.service
           ├─ 6957 /usr/libexec/cockpit-ws
           └─29598 /usr/bin/ssh-agent</pre>
</div>
</div>
<div class="paragraph">
<p>In order to customize who can perform various actions in system,
<a href="#privileges-polkit">create polkit rules</a> with the following actions
and details:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>org.freedesktop.systemd1.manage-units</code></dt>
<dd>
<p>Permission to manage system services or other units. Details
available: <code>unit</code>, <code>verb</code></p>
</dd>
<dt class="hdlist1"><code>org.freedesktop.systemd1.manage-unit-files</code></dt>
<dd>
<p>Permission to manage system services or other unit files.</p>
</dd>
<dt class="hdlist1"><code>org.freedesktop.systemd1.reload-daemon</code></dt>
<dd>
<p>Permission to reload the systemd state.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>For example, placing the following polkit rule to
<code>/etc/polkit-1/rules.d/10-http.rule</code> allows all users in the
<code>operators</code> group start, stop, and restart the Apache HTTP service:</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") &amp;&amp; action.lookup("unit") == "httpd.service") {
            var verb = action.lookup("verb");
            if (verb == "start" || verb == "stop" || verb == "restart") {
                return polkit.Result.YES;
            }
        }
    }
});</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="feature-journal">Journal</h3>
<div class="paragraph">
<p>The systemd journal provides Cockpit with indexed log data. This log
data is found on the Journal page, as well as in various other places
when configuring services, storage, networking etc.</p>
</div>
<div class="paragraph">
<p>Cockpit accesses Journal data via the
<a href="https://www.freedesktop.org/software/systemd/man/journalctl.html"><code>journalctl</code></a>
command. Similar tasks can be performed at the command line:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo journalctl -f -u docker
...</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="feature-networkmanager">NetworkManager</h3>
<div class="paragraph">
<p>If available on the system, Cockpit uses
<a href="https://wiki.gnome.org/Projects/NetworkManager">NetworkManager</a> and the
DBus APIs it provides to interact with the system&#8217;s network
configuration.</p>
</div>
<div class="paragraph">
<p>For non root users, NetworkManager controls access to its APIs via
<a href="#privileges">Policy Kit</a> and a user logged into Cockpit will have
the same permissions as they do from the command line.</p>
</div>
<div class="paragraph">
<p>To perform similar tasks from the command line, use the
<a href="https://fedoraproject.org/wiki/Networking/CLI">nmcli</a> command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ nmcli general status
STATE      CONNECTIVITY  WIFI-HW  WIFI     WWAN-HW  WWAN
connected  full          enabled  enabled  enabled  enabled</pre>
</div>
</div>
<div class="paragraph">
<p>Devices marked as "not managed" with the <code>NM_CONTROLLED=no</code> setting
will not be displayed in the interface.</p>
</div>
</div>
<div class="sect2">
<h3 id="feature-firewall">Firewall</h3>
<div class="paragraph">
<p>Cockpit uses <a href="https://www.firewalld.org">firewalld</a> to interact with the
system&#8217;s firewall. No firewall configuration UI will be shown if
firewalld is not installed.</p>
</div>
<div class="paragraph">
<p>Firewalld controls access to its APIs via PolicyKit. The user logged
into Cockpit needs to have the appropriate permissions to view or modify
the settings.</p>
</div>
<div class="paragraph">
<p>Cockpit can currently only show, add, and remove predefined firewalld
services in the default zone.</p>
</div>
<div class="paragraph">
<p>To perform similar tasks from the command line, use
<a href="https://www.firewalld.org/documentation/man-pages/firewall-cmd.html">firewall-cmd</a>.
For example, to get the same list of allowed services that Cockpit
displays:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo firewall-cmd --list-services
dhcpv6-client samba-client mdns ssh cockpit</pre>
</div>
</div>
<div class="paragraph">
<p>To enable an additional service, use:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ firewall-cmd --add-service pop3
success</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="feature-storaged">storaged</h3>
<div class="paragraph">
<p>If available on the system, Cockpit uses
<a href="https://github.com/storaged-project/storaged/"><code>storaged</code></a> to configure
and monitor storage, disks, mounts etc. on the system. This
functionality is present in the Cockpit <em>storaged</em> package.</p>
</div>
<div class="paragraph">
<p>The <code>storaged</code> project is originally based on a project called
<a href="https://www.freedesktop.org/wiki/Software/udisks/"><code>udisks</code></a> and added
support for many more features such as
<a href="https://en.wikipedia.org/wiki/Logical_Volume_Manager_(Linux)">LVM</a>,
<a href="https://en.wikipedia.org/wiki/ISCSI">iSCSI</a>,
<a href="https://en.wikipedia.org/wiki/Linux_DM_Multipath">Multipath</a>, and
<a href="https://btrfs.wiki.kernel.org/index.php/Main_Page">BTRFS</a>. The same tools
and backwards compatible API are available between <code>storaged</code> and
<code>udisks</code> the projects. Cockpit can use <code>udisks</code> but disables many of
it&#8217;s storage related features, including updating <code>/etc/fstab</code> and
<code>/etc/crypttab</code> for stability reasons.</p>
</div>
<div class="paragraph">
<p>For non root users, storaged controls access to its APIs via
<a href="#privileges">Policy Kit</a> and a user logged into Cockpit will have
the same permissions as they do from the command line.</p>
</div>
<div class="paragraph">
<p>To perform similar tasks from the command line, use the <code>storagedctl</code>
command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ udisksctl dump
...</pre>
</div>
</div>
<div class="paragraph">
<p>To perform LVM tasks, you may use the various LVM commands, such as
<code>vgcreate</code>, <code>lvresize</code> and so on. Cockpit will detect such changes
made at the command line.</p>
</div>
<div class="paragraph">
<p>Cockpit recognizes devices with multiple paths and can start the
<code>multipathd</code> service in case it is not running. On the command line,
you can control multipath features with the <code>mpathconf</code>,
<code>multipathd</code>, and <code>multipath</code> commands.</p>
</div>
<div class="paragraph">
<p>To manage iSCSI initiators from the command line, you can use
<code>iscsiadm</code> and related tools.</p>
</div>
</div>
<div class="sect2">
<h3 id="feature-users">User Tools</h3>
<div class="paragraph">
<p>Cockpit uses the usual tools to create and modify local user accounts.
Examples are <code>useradd</code>, <code>usermod</code> and <code>passwd</code>. These same tools
are available for use on the command line.</p>
</div>
</div>
<div class="sect2">
<h3 id="feature-realmd">realmd</h3>
<div class="paragraph">
<p>If available on the system, Cockpit uses
<a href="https://www.freedesktop.org/software/realmd/">realmd</a> and the DBus APIs
it provides to configure the system&#8217;s Active Directory or IPA domain
membership.</p>
</div>
<div class="paragraph">
<p>Not all systems can join all kinds of domains. This depends on the
availability of the necessary client software.</p>
</div>
<div class="paragraph">
<p>For non root users, realmd controls access to its APIs via
<a href="#privileges">Policy Kit</a> and a user logged into Cockpit will have
the same permissions as they do from the command line.</p>
</div>
<div class="paragraph">
<p>To perform similar tasks from the command line, use the
<a href="https://www.freedesktop.org/software/realmd/docs/realm.html">realm</a>
command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ realm join example.com
Password for Administrator:</pre>
</div>
</div>
<div class="paragraph">
<p><a href="http://www.freedesktop.org/software/realmd/">realmd</a> sets up
domain-qualified user names by default, i. e. login user names look like
&#8220;user@example.com&#8221;. For using unqualified names (just &#8220;user&#8221;),
set the <code>fully-qualified-names</code> option in
<a href="https://www.freedesktop.org/software/realmd/docs/realmd-conf.html">/etc/realmd.conf</a>
before joining a domain.</p>
</div>
<div class="paragraph">
<p>Cockpit requests an SSL certificate from the IPA server for
<code>cockpit-ws</code> with the
<a href="https://www.freeipa.org/page/Certmonger">ipa-getcert</a> command.</p>
</div>
</div>
<div class="sect2">
<h3 id="feature-terminal">Terminal</h3>
<div class="paragraph">
<p>Cockpit provides a standard shell in a terminal. This shell and the
processes running in it have the <a href="#privileges">same privileges</a> as if
the user had logged in via SSH.</p>
</div>
</div>
<div class="sect2">
<h3 id="feature-pcp">PCP Metrics</h3>
<div class="paragraph">
<p>If available, Cockpit uses the <a href="https://pcp.io/">Performance Co-Pilot</a>
framework to gather metrics data about the system. This data is used to
display the history graphs on the "Metrics and history" page. Cockpit
can use the PCP logging feature to display archived data about the
system from a different point in time. If PCP is not available, then
Cockpit gathers the metrics data itself, but archival features are not
available.</p>
</div>
<div class="paragraph">
<p>Whether or not metrics are archived depends on whether the
<a href="https://linux.die.net/man/1/pmlogger"><code>pmlogger.service</code></a> systemd unit
is running or not. The "Enable PCP metrics collector" button on the
Metrics page will enable and start this service.</p>
</div>
<div class="paragraph">
<p>To see similar metrics data from the command line, you can use tools
like <a href="https://linux.die.net/man/1/pmstat"><code>pmstat</code></a> or
<a href="https://linux.die.net/man/1/pminfo"><code>pminfo</code></a>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ pmstat
@ Sat Sep 26 15:30:10 2015
 loadavg                      memory      swap        io    system         cpu
   1 min   swpd   free   buff  cache   pi   po   bi   bo   in   cs  us  sy  id
    4.19      0 20710m 605148  6450m    0    0    0 2548 5688  14K  19   3  76
...</pre>
</div>
</div>
<div class="paragraph">
<p>These metrics can also be exposed to other machines on a TCP port with
<a href="https://linux.die.net/man/1/pmproxy">pmproxy</a> and
<a href="https://redis.io/">Redis</a> or <a href="https://valkey.io/">Valkey</a>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>systemctl enable --now redis pmproxy
# if you use firewalld, open port 44322:
firewall-cmd --permanent --add-service pmproxy
firewall-cmd --reload</pre>
</div>
</div>
<div class="paragraph">
<p>This allows you to gather and visualize PCP metrics from multiple
machines with <a href="https://grafana.com/">Grafana</a> and the
<a href="https://grafana-pcp.readthedocs.io">PCP Grafana plugin</a>.</p>
</div>
</div>
<div class="sect2">
<h3 id="feature-machines">Multiple Machines</h3>
<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 can connect to multiple machines from a single Cockpit session.
These are listed in the host switcher.</p>
</div>
<div class="paragraph">
<p>These additional machines are accessed via SSH from the machine that the
first machine connected to, and are <a href="#authentication">authenticated</a>
with the logged in user&#8217;s password and/or SSH keys.</p>
</div>
<div class="paragraph">
<p>SSH host keys are stored in <code>/etc/ssh/ssh_known_hosts</code>.</p>
</div>
<div class="paragraph">
<p>The machine data is stored in <code>/etc/cockpit/machines.d/*.json</code>, or
below <code>$XDG_CONFIG_DIRS</code> if set (see
<a href="./cockpit.conf.5.html">cockpit.conf</a>). Settings in lexicographically
later files amend or override settings in earlier ones. Cockpit itself
writes into <code>99-webui.json</code>; packages or admins who want to
pre-configure machines should ship files like <code>05-mymachine.json</code> so
that changes from the web interface override the pre-configured files.</p>
</div>
<div class="paragraph">
<p>Each JSON file contains an object that maps machine IDs to objects that
define the properties of that machine. The ID can be a human readable
name or an IP address or any other unique value, and is shown in the web
interface until conneting to it the first time, at which point the web
interface will show the machine&#8217;s host name.</p>
</div>
<div class="paragraph">
<p>The following properties are recognized:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>"address"</code></dt>
<dd>
<p><em>(string, mandatory)</em> IP address or DNS name of the machine</p>
</dd>
<dt class="hdlist1"><code>"visible"</code></dt>
<dd>
<p><em>(boolean, optional)</em> If <code>true</code>, the machine will be displayed and
available for managing with Cockpit. If <code>false</code> (the default), it
will not be displayed, but still taken into account for type-ahead
search when adding new machines in the web interface.</p>
</dd>
<dt class="hdlist1"><code>"user"</code></dt>
<dd>
<p><em>(string, optional)</em> User name on the remote machine. When not given,
Cockpit will default to the user name that was being used to log into
Cockpit itself.</p>
</dd>
<dt class="hdlist1"><code>"port"</code></dt>
<dd>
<p><em>(integer, optional)</em> ssh port of the remote machine. When not given,
the default port 22 is used.</p>
</dd>
<dt class="hdlist1"><code>"color"</code></dt>
<dd>
<p><em>(string, optional)</em> Color to assign to the machine label in the web
interface. This can be either given as
<code>rgb(r_value, g_value, b_value)</code> with each value being an integer
between 0 and 255, or as a color name like <code>yellow</code>. When not given,
Cockpit will assign an unused color automatically.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Example:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{
    "web server": {
        "address": "192.168.2.4",
        "visible": true,
        "color": "rgb(100, 200, 0)",
        "user": "admin"
    },
    "192.168.2.1": {
        "address": "192.168.2.1",
        "port": 2222,
        "visible": true,
        "color": "green"
    }
}</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="feature-selinux">SELinux Policy</h3>
<div class="paragraph">
<p>If present on the system Cockpit can set the SELinux mode to enforcing
or permissive. It can also use <code>setroubleshootd</code> to show audit issues
and apply suggested fixes.</p>
</div>
<div class="paragraph">
<p>To perform similar tasks from the command line use the <code>setenforce</code>
and <code>sealert</code> tools.</p>
</div>
<div class="paragraph">
<p>To clear out all the information that <code>setroubleshootd</code> tracks, you
can use a commands like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ sudo killall setroubleshootd
$ sudo rm -rf /var/lib/setroubleshoot/*</pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="feature-tuned">Tuned Profiles</h3>
<div class="paragraph">
<p>If present on the system Cockpit can use Tuned and the DBUS API it
provides to set system performance profiles. To perform similar tasks
from the command line, use the <code>tuned-adm</code> command.</p>
</div>
</div>
<div class="sect2">
<h3 id="feature-sosreport">SOS Report</h3>
<div class="paragraph">
<p>If present on the system Cockpit can use <code>sosreport</code> to collect system
configuration and diagnostic information.</p>
</div>
<div class="paragraph">
<p>To perform similar tasks from the command line, use the <code>sosreport</code>
command.</p>
</div>
</div>
<div class="sect2">
<h3 id="feature-packagekit">Package Updates</h3>
<div class="paragraph">
<p>Cockpit uses the
<a href="https://www.freedesktop.org/software/PackageKit/gtk-doc/api-reference.html">PackageKit</a>
D-Bus API to get information about available package updates and to
apply them, in an Operating System independent manner.</p>
</div>
<div class="paragraph">
<p>To perform similar tasks from the command line, use the
<a href="https://www.freedesktop.org/software/PackageKit/pk-using.html">pkcon</a>
command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ pkcon refresh

$ pkcon get-updates
Available  sudo-1.8.20p2-1.fc26.x86_64 (updates-testing)
    Allows restricted root access for specified users
Available  vim-filesystem-2:8.0.617-1.fc26.x86_64 (updates-testing)
    VIM filesystem layout
Available  vim-minimal-2:8.0.617-1.fc26.x86_64 (updates-testing)
    A minimal version of the VIM editor

$ pkcon get-update-detail sudo
Details about the update:6.x86_64 [fedora]
 Package: sudo-1.8.20p2-1.fc26.x86_64
 Bugzilla: https://bugzilla.redhat.com/show_bug.cgi?id=1452941
 Update text: - update to 1.8.20p2
    - added sudo package to dnf/yum protected packages

$ pkcon update
The following packages have to be updated:
 sudo-1.8.20p2-1.fc26.x86_64    Allows restricted root access for specified users
 vim-filesystem-2:8.0.617-1.fc26.x86_64 VIM filesystem layout
 vim-minimal-2:8.0.617-1.fc26.x86_64    A minimal version of the VIM editor
Proceed with changes? [N/y] y
[...]</pre>
</div>
</div>
<div class="paragraph">
<p>Of course you can also use your Operating System specific commands for
that, such as <code>dnf updateinfo info</code> on Fedora or <code>sudo apt upgrade</code>
on Debian.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="development">Developer Guide</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="embedding">Embedding and Integrating Cockpit</h3>
<div class="paragraph">
<p>Cockpit can be embedded in other web applications either as a whole or
specific Cockpit components can be integrated. Due to frame security
policy restrictions, this only works if Cockpit and the web application
have the <em>same origin</em>; this is commonly achieved by running both from a
common reverse proxy.</p>
</div>
<div class="sect3">
<h4 id="embedding-full">Embedding the Cockpit Interface</h4>
<div class="paragraph">
<p>Cockpit can be embedded into a larger web page as a frame. To embed the
entire Cockpit Window use the URI: <code>https://server.example.com:9090/</code></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-html" data-lang="html">&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;Embedded Cockpit&lt;/title&gt;
  &lt;/head&gt;
  &lt;body&gt;
    This is Cockpit.
    &lt;br/&gt;
    &lt;iframe width="800px" height="600px"
            src="https://server.example.com:9090/"/&gt;
  &lt;/body&gt;
&lt;/html&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="embedding-components">Integrating Cockpit Components into Web Applications</h4>
<div class="paragraph">
<p>Instead of embedding the entirety of Cockpit, you can integrate specific
components. Only those components explicitly documented as API should be
integrated. Other components can and will change regularly.</p>
</div>
<div class="paragraph">
<p>The component will load from the server in question and a WebSocket
connection will be established with the server to relay the component&#8217;s
message stream.</p>
</div>
<div class="paragraph">
<p>Cockpit components are HTML files contained in <a href="#packages">packages</a>.
These can be placed in an iframe or web browser window. Each documented
and stable component has a well-known URL and these are documented in
the <a href="#development">API reference</a>. Each component URL begins with the
string <code>/cockpit/@localhost/</code> followed a package name, and then the
component itself.</p>
</div>
<div class="paragraph">
<p>For example the <a href="#api-terminal-html">terminal.html</a> in the
<a href="#api-system">system</a> package, has this URL:
<code>/cockpit/@localhost/system/terminal.html</code></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-html" data-lang="html">&lt;html&gt;
  &lt;head&gt;
    &lt;title&gt;Embedded Terminal&lt;/title&gt;
  &lt;/head&gt;
  &lt;body&gt;
    This is a terminal.
    &lt;br/&gt;
    &lt;iframe width="800px" height="600px"
      src="https://server.example.com:9090/cockpit/@localhost/system/terminal.html"/&gt;
  &lt;/body&gt;
&lt;/html&gt;</code></pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="embedding-deep">Deep Integration</h4>
<div class="paragraph">
<p>Most often <a href="#embedding-components">simple integration</a> will be used
to bring Cockpit components into web applications. However it is also
possible to do deep integration for embedders who wish to perform
non-standard authentication with the server, and relay the component&#8217;s
message stream to the server themselves.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
<div class="paragraph">
<p>Deep integration capability is in heavy flux and is not yet documented.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="embedding-cors">Pinging Cockpit</h4>
<div class="paragraph">
<p>When embedding Cockpit or integrating Cockpit components, it may be
necessary to check whether Cockpit is available on a server before
proceeding.</p>
</div>
<div class="paragraph">
<p>To do this perform a <code>/ping</code> request to Cockpit. This is a simple HTTP
GET request. It returns the following:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>GET: https://server.example.com:9090/ping
200 OK: { "service": "cockpit" }</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>/ping</code> request allows
<a href="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">Cross Origin
Resource Sharing</a> headers and as such can be performed from Javascript
code with any origin. The request can also be made via plain HTTP
without SSL. It is by design that no further information is present in
the response.</p>
</div>
<div class="paragraph">
<p>A complete example of using <code>/ping</code> is available in the Cockpit
sources in the <code>/examples/ping-server/</code> directory.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="packages">Cockpit Packages</h3>
<div class="paragraph">
<p>Cockpit is separated into various packages, each of which brings
specific features and/or code.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
<div class="paragraph">
<p>In addition, any APIs or behavior not explicitly documented here is an
internal API and can be changed at any time.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="sect3">
<h4 id="package-layout">Layout of Package Files</h4>
<div class="paragraph">
<p>A package consists of one or more files placed in a directory or its
subdirectories. It must have a <code>manifest.json</code> file and follow certain
naming conventions.</p>
</div>
<div class="paragraph">
<p>The name of a package is the name of the directory.</p>
</div>
<div class="paragraph">
<p>The name of the package must be ASCII alphanumeric, and may contain an
underscore. Names of directories and files in the package must consist
of ASCII alphanumeric along with dash, underscore, dot, and comma. No
spaces are allowed.</p>
</div>
<div class="paragraph">
<p>Cockpit uses the data directories from the
<a href="https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
Base Directory Specification</a> to locate packages. The <code>$XDG_DATA_DIRS</code>
represents a colon separate list of system data directories, and
<code>$XDG_DATA_HOME</code> is a user specific data directory. If the environment
variables are not set, defaults are used, according to the spec. If
cockpit has been built with an alternate <code>--prefix=/path</code> then the
<code>$prefix/share/cockpit</code> is used by default.</p>
</div>
<div class="paragraph">
<p>A <code>cockpit/</code> subdirectories in any of these data directories is the
location where packages are loaded by Cockpit. If Cockpit finds a
package with the same name, in multiple data directories, then the first
one wins. According to the spec the first data directory is
<code>$XDG_DATA_HOME</code> and then <code>$XDG_DATA_DIRS</code> in order.</p>
</div>
<div class="paragraph">
<p>This means that, by default the following directories are searched for
cockpit packages, and in this order:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>~/.local/share/cockpit/</code></p>
</li>
<li>
<p><code>/usr/local/share/cockpit/</code></p>
</li>
<li>
<p><code>/usr/share/cockpit/</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Packages placed in <code>$XDG_DATA_HOME</code> are not cached by Cockpit or the
web browser. Other packages are cached aggressively, and are accessed
using a checksum of the files in the packages and their names.</p>
</div>
<div class="paragraph">
<p>You can use the following command to list the packages installed on a
server. You&#8217;ll note that it&#8217;s output may change when you run the command
as different users, if there are packages installed in the user&#8217;s home
directory.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>$ cockpit-bridge --packages
...</pre>
</div>
</div>
<div class="paragraph">
<p>To further clarify things, here is an example package called
"my-package" and its file layout:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>/usr/share/cockpit/
    my-package/
        manifest.json
        file.html
        some.js</pre>
</div>
</div>
<div class="paragraph">
<p>Place or symlink packages in your <code>~/.local/share/cockpit</code> directory
(or appropriate <code>$XDG_DATA_HOME</code> location) that you would like to
modify and develop. System installed packages should not change while
Cockpit is running.</p>
</div>
</div>
<div class="sect3">
<h4 id="_package_manifest">Package Manifest</h4>
<div class="paragraph">
<p>Each package has a <code>manifest.json</code> file. It is a JSON object. The
following fields may be present in the manifest:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">content-security-policy</dt>
<dd>
<p>By default Cockpit serves packages using a strict
<a href="https://en.wikipedia.org/wiki/Content_Security_Policy">Content Security
Policy</a>, which among other things does not allow inline styles or
scripts. This can be overridden on a per-package basis, with this
setting.
+
If the overridden content security policy does not contain a
<code>default-src</code>, <code>connect-src</code>, <code>base-uri</code>, <code>form-action</code>,
<code>object-src</code>, or <code>block-all-mixed-content</code> then these will be
added to the policy from the manifest.</p>
</dd>
<dt class="hdlist1">name</dt>
<dd>
<p>An optional string that changes the name of the package. Normally
packages derive their name from the directory that they are located
in. This field overrides that name.</p>
</dd>
<dt class="hdlist1">priority</dt>
<dd>
<p>An optional number that specifies which package is preferred in cases
where there are conflicts. For example given two packages with the
same <code>name</code> a package is chosen based on its priority.</p>
</dd>
<dt class="hdlist1">conditions</dt>
<dd>
<p>An optional list of <code>{"predicate": "value"}</code> objects. Cockpit will
only consider the package if <em>all</em> conditions are met. This is
preferable to using <code>priority</code>.<br>
<br>
Currently supported predicates are <code>path-exists</code> and <code>path-not-exists</code>
(since Cockpit 286) and <code>any</code> (since Cockpit 348). <code>any</code> accepts a
list of conditions and evaluates to true if <em>at least one</em> of the nested
conditions is met. Unknown predicates are ignored.</p>
</dd>
<dt class="hdlist1">requires</dt>
<dd>
<p>An optional JSON object that contains a <code>"cockpit"</code> string version
number. The package will only be usable if the Cockpit bridge and
javascript base are equal or newer than the given version number.</p>
</dd>
<dt class="hdlist1">version</dt>
<dd>
<p>An informational version number for the package.</p>
</dd>
<dt class="hdlist1">preload</dt>
<dd>
<p>A list of identifiers of the components that should be preloaded.
Normally, the files of a component are loaded when the user navigates
to it for the first time. The files of a preloaded component are
loaded immediately after the user logs in, and the initialization code
of the component is invoked.
+
The value of this field is an array of strings, where each string is
one of the keys used in the <code>dashboard</code>, <code>menu</code>, or <code>tool</code>
fields that are explained below.</p>
</dd>
<dt class="hdlist1">parent</dt>
<dd>
<p>This option is used when module does not have its own menu item but is
a part of a different module. This is described by JSON object with
properties <code>component</code> which takes name of the superordinate
component and <code>docs</code> with list of documentation URLs for the given
page. See below for structure of <code>docs</code> property.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>In addition, the following keys contain information about where
components of the package should appear in Cockpit&#8217;s user interface.
Each of these keys is optional and contains an object mapping unique
identifiers to menu items, which are described below. (The naming of
these fields doesn&#8217;t perfectly match the current user interface for
historical reasons.)</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">dashboard</dt>
<dd>
<p>Dashboard items appear in the menu under the section <em>Apps</em>.</p>
</dd>
<dt class="hdlist1">menu</dt>
<dd>
<p>These items appear in the menu under the section <em>System</em>. This
section is roughly ordered into these categories (with their <em>order</em>
in parentheses):
+</p>
<div class="ulist">
<ul>
<li>
<p>System Information (10)</p>
</li>
<li>
<p>Logs (20)</p>
</li>
<li>
<p>Configuring major subsystems (30-40)</p>
</li>
<li>
<p>Things running on the machine (VMs, Containers - 50-60)</p>
</li>
<li>
<p>Implementation Details (Accounts, Services - 70-100)</p>
</li>
</ul>
</div>
</dd>
<dt class="hdlist1">tools</dt>
<dd>
<p>These items appear in the menu under the section <em>Tools</em>.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Menu items and tools are registered using JSON objects that have the
following properties:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">label</dt>
<dd>
<p>The label for the menu item or tool.</p>
</dd>
<dt class="hdlist1">order</dt>
<dd>
<p>An optional order number to place this menu item or tool. Lower
numbers are listed first.</p>
</dd>
<dt class="hdlist1">path</dt>
<dd>
<p>The relative path to the HTML file within the package that implements
the menu item or tool.</p>
</dd>
<dt class="hdlist1">docs</dt>
<dd>
<p>List of documentation URLs for the given page. Each item is an object
containing <code>label</code> and <code>url</code>.</p>
</dd>
<dt class="hdlist1">keywords</dt>
<dd>
<p>Keywords that describe the page and which are used for searching.
These keywords should be lowercase. Keywords is a list containing
keyword items as described below. Page label is prepended as first
keyword in the first keyword item.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Keyword items are registered using JSON objects that have the following
properties:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">matches</dt>
<dd>
<p>List of keywords to be matched.</p>
</dd>
<dt class="hdlist1">goto</dt>
<dd>
<p>Optional path that is used for all keywords in this item. When this
argument starts with slash, then it is used as pathname, otherwise it
is used as hash. Defining <code>goto:"page_hash"</code> in page with
<code>path:"/page_path"</code> would redirect to <code>/page_path#page_hash</code>,
while <code>goto:"/page_path"</code> would redirect to <code>/page_path</code> ignoring
default page path.</p>
</dd>
<dt class="hdlist1">weight</dt>
<dd>
<p>How much keywords are prioritized over others. Default is 3.</p>
</dd>
<dt class="hdlist1">translate</dt>
<dd>
<p><code>false</code> when keywords should not be localized. Default is <code>true</code>.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>An example manifest.json with some optional properties set:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{
  "version": 0,
  "require": {
      "cockpit": "120"
  },
  "tools": {
     "mytool": {
        "label": "My Tool",
        "path": "tool.html"
     }
  }
}</pre>
</div>
</div>
<div class="literalblock">
<div class="content">
<pre>{
  "version": 0,
  "require": {
    "cockpit": "120"
  },
  "conditions": [
    {"path-exists": "/usr/bin/mytool"},
    {"path-exists": "/etc/mytool.conf"},
    {"path-not-exist": "/etc/incompatible-tool"}
  ],
  "tools": {
     "mytool": {
        "label": "My Tool",
        "path": "tool.html"
     }
  }
}</pre>
</div>
</div>
<div class="paragraph">
<p>The following example shows how to use disjunctive conditions with <code>any</code>
to specify alternative requirements (available since Cockpit 348). This
package will be available if either <code>/usr/bin/alt1</code> or <code>/usr/bin/alt2</code>
exists. In any case, <code>/etc/incompatible-tool</code> must not exist.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>"conditions": [
  {"any": [{"path-exists": "/usr/bin/alt1"}, {"path-exists": "/usr/bin/alt2"}]},
  {"path-not-exists": "/etc/incompatible-tool"}
]</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="package-manifest-override">Manifest overrides</h4>
<div class="paragraph">
<p>To change a manifest system-wide, a file
<code>&lt;package-directory-name&gt;.override.json</code> may be placed into
<code>/etc/cockpit/</code>, or below <code>$XDG_CONFIG_DIRS</code> if set (see
<a href="./cockpit.conf.5.html">cockpit.conf</a>). To change it for a particular
user only, put the override into <code>~/.config/cockpit</code>.</p>
</div>
<div class="paragraph">
<p>These override the information in the manifest in the simple
<a href="https://tools.ietf.org/html/rfc7386">JSON Merge Patch</a> format.</p>
</div>
<div class="paragraph">
<p>This can be used to hide or modify menu items of an existing package.
For example <code>/etc/cockpit/systemd.override.json</code> or
<code>~/.config/cockpit/systemd.override.json</code> could hide the <em>Logs</em> menu
item and move the <em>Services</em> menu item to the top of the menu.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{
  "menu": {
    "logs": null,
    "services": {
      "order": -1
    }
  }
}</pre>
</div>
</div>
</div>
<div class="sect3">
<h4 id="package-links">Package Links and Paths</h4>
<div class="paragraph">
<p>When referring to files in your package, such as in a hyperlink or a
<code>&lt;style&gt;</code> tag or <code>&lt;script&gt;</code> tag, simply use a relative path, and
refer to the files in the same directory. When you need to refer to
files in another package use a relative link.</p>
</div>
<div class="paragraph">
<p>For example here&#8217;s how to include the base <code>cockpit.js</code> script in your
HTML from the <code>latest</code> package:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>&lt;script src="../base1/cockpit.js"&gt;&lt;/script&gt;</pre>
</div>
</div>
<div class="paragraph">
<p>Do not assume you can link to any file in any other package. Refer to
the <a href="#development">list of API packages</a> for those that are available
for use.</p>
</div>
</div>
<div class="sect3">
<h4 id="package-minified">Content Negotiation</h4>
<div class="paragraph">
<p>In order to support gzipped and/or minified data, the files in a package
are loaded using content negotiation logic. A HTTP request for the file
<code>test.js</code> in the package named <code>mypackage</code> will return
<code>mypackage/test.js</code> or <code>mypackage/test.js.gz</code> (in undefined
preference). If neither exists, then it returns
<code>mypackage/test.js.min</code> or <code>mypackage/test.js.min.gz</code> (again in
undefined preference).</p>
</div>
<div class="paragraph">
<p>When packages are loaded from a system directory, Cockpit optimizes the
file system lookups above, by pre-listing the files. This is one of the
reasons that you should never change packages installed to a system
directory while Cockpit is running.</p>
</div>
</div>
<div class="sect3">
<h4 id="package-api">Using Cockpit API</h4>
<div class="paragraph">
<p>Cockpit has API available for writing packages. There is no API
available for external callers to invoke via HTTP, REST or otherwise.</p>
</div>
<div class="paragraph">
<p>API from various packages can be used to implement Cockpit packages.
Each package listed here has some API available for use. Only the API
explicitly documented should be used.</p>
</div>
<div class="ulist">
<ul>
<li>
<p><a href="#development">API Listing</a></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>To include javascript from the API, simply load it into your HTML using
a script tag. Alternatively you can use an javascript loader.</p>
</div>
</div>
<div class="sect3">
<h4 id="package-bridges">Bridges for specific tasks</h4>
<div class="paragraph">
<p>On the server side the <a href="#cockpit-bridge.1"><code>cockpit-bridge</code></a>
connects to various system APIs that the front end UI requests it to.
There are additional bridges for specific tasks that the main
<code>cockpit-bridge</code> cannot handle, such as using the PCP C library API.</p>
</div>
<div class="paragraph">
<p>These additional bridges can be registered in a <code>"bridges"</code> section of
a package&#8217;s <code>manifest.json</code> file. Building such a bridge is a complex
tasks, and we will skip over that here. However it is useful to adjust
how these additional bridges are called, and so we&#8217;ll look at how they
are registered.</p>
</div>
<div class="paragraph">
<p>An example <code>manifest.json</code> with a bridges section:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{
    "bridges": [
        {
            "match": { "payload": "metrics1" },
            "spawn": [ "/usr/libexec/cockpit-pcp" ]
        }
    ]
}</pre>
</div>
</div>
<div class="paragraph">
<p>The bridges are considered in the order they are listed in the array.
Use the <code>manifest.json`</code>"priority"` field to control order between
packages. The bridges are registered using JSON objects that have the
following properties:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">environ</dt>
<dd>
<p>Optional, additional environment variables to pass to the bridge
command.</p>
</dd>
<dt class="hdlist1">match</dt>
<dd>
<p>The <code>"match"</code> object describes which channel open command options
need to match for a given channel to be handed over to this bridge.</p>
</dd>
<dt class="hdlist1">privileged</dt>
<dd>
<p>If set to <code>true</code>, this marks the bridge as a superuser bridge.
Cockpit will start one of these explicitly when trying to escalate the
privileges of a session. A privileged bridge can not have a
<code>"match"</code> property.</p>
</dd>
<dt class="hdlist1">label</dt>
<dd>
<p>Setting this enables selection of privileged bridges in the UI. When
no privileged bridge has a <code>label</code>, then Cockpit will start the
bridge that runs <code>sudo</code>. This is the case in a default Cockpit
installation. When at least one privileged bridge has a <code>label</code> then
the user can select one of them when escalating privileges. As a
special case, if only one bridge has a <code>label</code>, then the step of
selecting a bridge is omitted in the UI and that one bridge is always
started.
+
Thus, if you add a privileged bridge with a <code>label</code> in a new
manifest, Cockpit will use that bridge the next time a user opens the
"Administrative access" dialog. If you want the user to choose between
the <code>sudo</code> method and your new one, you need to duplicate the
<code>sudo</code> bridge definition in your manifest and give it a label.</p>
</dd>
<dt class="hdlist1">problem</dt>
<dd>
<p>If a problem is specified, and this bridge fails to start up then
channels will be closed with this problem code. Otherwise later
bridges or internal handlers for the channel will be invoked.</p>
</dd>
<dt class="hdlist1">spawn</dt>
<dd>
<p>The command and arguments to invoke.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The <code>spawn</code> and <code>environ</code> values can be dynamically taken from a
matching open command values. When a value in either the <code>spawn</code> or
<code>environ</code> array contains a named variable wrapped in <code>${}</code>, the
variable will be replaced with the value contained in the matching open
command. Only named variables are supported and name can only contain
letters, numbers and the following symbols: <code>._-</code></p>
</div>
<div class="paragraph">
<p>For example a bridges section like:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{
  "bridges": [
    {
      "match": { "payload": "example" },
      "environ": [ "TAG=${tag}" ],
      "spawn: [ "/example-bridge", "--tag", "${tag}" ],
      "problem": "access-denied"
    }
  ]
}</pre>
</div>
</div>
<div class="paragraph">
<p>when a open command is received with a payload of <code>example</code> with
<code>tag</code> value of <code>tag1</code>. The following command will be spawned</p>
</div>
<div class="literalblock">
<div class="content">
<pre>TAG=tag1 /example-bridge --tag tag1</pre>
</div>
</div>
<div class="paragraph">
<p>Processes that are reused so if another open command with a "tag" of
<code>tag1</code> is received. The open command will be passed to existing
process, rather than spawning a new one. However a open command with an
tag of <code>tag2</code> will spawn a new command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>TAG=tag2 /example-bridge --tag tag2</pre>
</div>
</div>
<div class="paragraph">
<p>If you need to include <code>${}</code>, as an actual value in your arguments you
can escape it by prefixing it with a <code>\</code></p>
</div>
</div>
<div class="sect3">
<h4 id="package-replace">Replacing an existing package</h4>
<div class="paragraph">
<p>If the functionality in a package replaces that of another package then
it can replace that package by claiming the same <code>name</code> and a higher
<code>priority</code>.</p>
</div>
<div class="paragraph">
<p>For example, a package in the <code>/usr/share/cockpit/disks</code> directory
could replace Cockpit&#8217;s <em>storage</em> package with a <code>manifest.json</code> like
this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{
  "version": 0,
  "name": "storage",
  "priority": 10,
  "menu": {
     "index": {
        "label": "Disk Storage",
        "order": 15
     }
  }
}</pre>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="urls">Cockpit URLs</h3>
<div class="paragraph">
<p>Cockpit URLs follow a specific structure, related to the components they
are loading. Various components are loaded in <code>&lt;iframe&gt;</code> tags. The
URLs for these components are described first. Further down below you
can find information about the top level bookmarkable Cockpit address
URLs.</p>
</div>
<div class="sect3">
<h4 id="urls-components">Component URLs</h4>
<div class="paragraph">
<p>Cockpit components are HTML documents. They are organized into
<a href="#packages">packages</a>. Each package contains information about which
HTML components are available in that package. Components should always
use relative URLs to access resources, such as images, scripts or CSS
files, even if they refer to a resource in another package.</p>
</div>
<div class="paragraph">
<p>The following are valid component URLs, each bit will be discussed
below:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>/cockpit/@localhost/package/component.html#/hash
/cockpit/$checksum/package/component.html#/hash
/cockpit/@server.example.com/package/component.html#/hash
/cockpit+embedder/@localhost/package/component.html#/hash</pre>
</div>
</div>
<div class="paragraph">
<p>All resource URLs are under the <code>/cockpit</code> namespace. In cases where a
Cockpit component is being <a href="#embedding">embedded</a> the <code>/cockpit</code>
may be followed by a plus sign and another <code>embedder</code> specific
identifier.</p>
</div>
<div class="paragraph">
<p>What follows is either a <code>@host</code> or <code>$checksum</code> which tells cockpit
where to <a href="#packages">find the package</a>. Checksums are used when more
than one host has identical packages and the resources can be cached.</p>
</div>
<div class="paragraph">
<p>The <code>package</code> name is next, followed by the <code>component</code> HTML path
inside that package. And lastly a hash allows for navigation within a
single component. The hash should follow a URL path and/or query string
form.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
<div class="paragraph">
<p>Never assume that the <code>@host</code> or <code>$checksum</code> portion is predictable.
Only refer to resources in packages on the same host.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect3">
<h4 id="urls-visible">Visible URLs</h4>
<div class="paragraph">
<p>The above Component URLs are usually not visible to the user. Instead
the Cockpit Web Service wraps the components in a shell which allows
navigation, and provides bookmarkable clean URLs to the component. These
URLs do not affect <a href="#embedding">embedders</a> or
<a href="#packages">components</a> directly.</p>
</div>
<div class="paragraph">
<p>If no path is present then the Cockpit will redirect to the default page
for the server.</p>
</div>
<div class="paragraph">
<p>If the first segment of the path begins with an <code>@</code> sign, then the
component is being shown from a non-local host.</p>
</div>
<div class="paragraph">
<p>The next segment of the path, (or first if the component is being shown
on the local host) is the <a href="#packages">package name</a>. The remainder of
the path is a component file in the package. If no further path segments
are present, a default <code>index.html</code> component in the package is
loaded. An extension of <code>.html</code> is automatically appended.</p>
</div>
<div class="paragraph">
<p>The hash portion of the path is automatically transferred to the
component as the hash of its <a href="#urls-components">resource URL</a>.</p>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_api_base1">API: base1</h3>
<div class="paragraph">
<p>This package contains basic support API available to other packages.</p>
</div>
<div class="sect3">
<h4 id="_cockpit_js">cockpit.js</h4>
<div class="paragraph">
<p>Basic cockpit API to interact with the system</p>
</div>
<div class="sect4">
<h5 id="api-cockpit-loading">Loading cockpit.js</h5>
<div class="paragraph">
<p><code>cockpit.js</code> should be loaded via a script tag.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>&lt;script src="../base1/cockpit.js"&gt;</pre>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_object_caching">cockpit.js: Object Caching</h4>
<div class="paragraph">
<p>If the same information is displayed by multiple components in Cockpit,
<code>cockpit.cache()</code> provides a way to share data between them. The
shared data should be simple objects, arrays, and values, and not
contain functions or other objects.</p>
</div>
<div class="sect4">
<h5 id="cockpit-cache-func">cockpit.cache()</h5>
<div class="literalblock">
<div class="content">
<pre>cache = cockpit.cache(key, provider, consumer)</pre>
</div>
</div>
<div class="paragraph">
<p>Create a new cache object. The <code>key</code> should be a globally unique
string that describes the data being cached. This string must describe
the data, across all machines and all versions of cockpit. It is
customary to include a version number in the <code>key</code> string.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>function provider(result, key) {
    result("myvalue");

    return {
        close: function() {
            /* closed */
        }
    };
}</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>provider</code> is a function that will be invoked to start retrieving
data for the cache. It will be passed a <code>result</code> function as its first
argument. The <code>result</code> should be invoked whenever new data is
available. The <code>key</code> argument matches the key string the cache was
created with.</p>
</div>
<div class="paragraph">
<p>The <code>provider</code> can return an object with a <code>close</code> method. This
method will be invoked when the cache no longer needs data from the
provider.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>function consumer(value, key) {
    /* ... */
}</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>consumer</code> is a function that will be passed new values when they
are available, whether they come from the <code>provider</code> or a source in a
different component/frame.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-cache-close">cache.close()</h5>
<div class="literalblock">
<div class="content">
<pre>cache.close()</pre>
</div>
</div>
<div class="paragraph">
<p>Close a cache and stop calling its <code>consumer</code>. If the <code>provider</code> was
invoked, then the <code>close()</code> method it returned will be invoked.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_raw_channels">cockpit.js: Raw Channels</h4>
<div class="paragraph">
<p>At a low level Cockpit communicates with the system via messages passed
through various channels. These are usually exposed via higher level
APIs, such as the <code>cockpit.spawn()</code> function. It is rare to use raw
channels directly.</p>
</div>
<div class="sect4">
<h5 id="cockpit-channels-channel">cockpit.channel()</h5>
<div class="literalblock">
<div class="content">
<pre>channel = cockpit.channel(options)</pre>
</div>
</div>
<div class="paragraph">
<p>This function creates a new channel for communication with the system.
It returns a new channel object. The <code>options</code> argument is a plain
object. At least the <code>"payload"</code> option is required, and based on the
payload type, other options may be required.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>"binary"</code></dt>
<dd>
<p>Set to <code>true</code> to transfer binary payloads. Both messages sent via
<a href="#cockpit-channels-send"><code>channel.send()</code></a> and those received via
<a href="#cockpit-channels-message"><code>channel.onmessage</code></a> should be arrays
of bytes, either <code>Uint8Array</code> or <code>Array</code> depending on browser
support.</p>
</dd>
<dt class="hdlist1"><code>"payload"</code></dt>
<dd>
<p>The payload type for the channel. Only specific payload types are
supported.</p>
</dd>
<dt class="hdlist1"><code>"superuser"</code></dt>
<dd>
<p>Set to <code>"require"</code> to open this channel as root. If the currently
logged in user is not permitted to become root (eg: via <code>pkexec</code>)
then the <code>channel</code> will immediately be
<a href="#cockpit-channels-close-ev">closed</a> with a <code>"access-denied"</code>
problem code.
+
Set to <code>"try"</code> to try to open the channel as root, but if that
fails, then fall back to an unprivileged channel.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The channel object returned has the following fields and methods and
events. You should call the <code>channel.close()</code> method when done with
the channel.</p>
</div>
<div class="paragraph">
<p>A valid channel will always be returned and the is ready to
<code>channel.send()</code>. The channel may
<a href="#cockpit-channels-close-ev">close shortly afterword</a> due to a
failure.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-channels-binary">channel.binary</h5>
<div class="paragraph">
<p>Will be <code>true</code> for an binary channel. Will be set to <code>false</code> if the
channel is textual.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-channels-options">channel.options</h5>
<div class="paragraph">
<p>The options used to open this channel. This should not be changed.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-channels-valid">channel.valid</h5>
<div class="paragraph">
<p>Will be <code>true</code> for an open channel. Will be set to <code>false</code> if the
channel closes.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-channels-send">channel.send()</h5>
<div class="literalblock">
<div class="content">
<pre>channel.send(data)</pre>
</div>
</div>
<div class="paragraph">
<p>Send a message over the channel. The contents of the message depends on
the payload type of the channel. If a binary channel, then <code>data</code> is
expected to be an <code>Array</code> of bytes or a <code>Uint8Array</code>. If not binary,
then the <code>data</code> will be converted to a string if not already a string.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-channels-control">channel.control()</h5>
<div class="literalblock">
<div class="content">
<pre>channel.control(options)</pre>
</div>
</div>
<div class="paragraph">
<p>Notify the channel to tune certain parameters on the fly. The
<code>options</code> is a plain javascript object, and the contents depend on the
<code>"payload"</code> of the channel.</p>
</div>
<div class="paragraph">
<p>One common operation is to set <code>"command"</code> to <code>"done"</code> in the
options field. To indicate that no further messages will be sent through
the channel.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-channels-wait">channel.wait()</h5>
<div class="literalblock">
<div class="content">
<pre>promise = channel.wait([callback])</pre>
</div>
</div>
<div class="paragraph">
<p>Returns a <code>promise</code> that is ready when the channel is ready, or fails
if the client closes. If a <code>callback</code> is specified, it is attached to
the promise. The promise will be rejected or resolved with the contents
<code>options</code> passed to the
<a href="#cockpit-channels-onready">channel.onready</a> and
<a href="#cockpit-channels-close-ev">channel.onclose</a> events respectively.</p>
</div>
<div class="paragraph">
<p>In general it&#8217;s not necessary to wait for the channel before starting to
use the channel.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-channels-close">channel.close()</h5>
<div class="literalblock">
<div class="content">
<pre>channel.close([options])</pre>
</div>
</div>
<div class="paragraph">
<p>Close the channel.</p>
</div>
<div class="paragraph">
<p>If <code>options</code> is present it can be a plain javascript object containing
additional channel close options to send to the peer. If closing for
because of a problem, set the <code>"problem"</code> field to a
<a href="#cockpit-problems">problem code</a>. If <code>options</code> is not an object it
will be treated as a <code>"problem"</code>.</p>
</div>
<div class="paragraph">
<p>The <a href="#cockpit-channels-close-ev">close event</a> will fire. A channel
can also be closed by a peer or if the underlying transport closes.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-channels-message">channel.onmessage</h5>
<div class="literalblock">
<div class="content">
<pre>channel.addEventListener("message", function(event, data) { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>An event triggered when the channel receives a message. The message is
passed as a string to the handler in the <code>data</code>. In the case of binary
channels <code>data</code> is an <code>Uint8Array</code> or an <code>Array</code> of bytes if the
former is not supported by the browser. The contents of the message
depends on the payload type of the channel.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-channels-oncontrol">channel.oncontrol</h5>
<div class="literalblock">
<div class="content">
<pre>channel.addEventListener("control", function(event, options) { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>An event triggered when the channel receives an control message in the
middle of the flow. One particular use is when the <code>command</code> is set to
<code>"done"</code> then no further messages will be received in the channel. The
exact form of these messages depend on the <code>"payload"</code> of the channel.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-channels-onready">channel.onready</h5>
<div class="literalblock">
<div class="content">
<pre>channel.addEventListener("ready", function(event, options) { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>An event triggered when the other end of the channel is ready to start
processing messages. This indicates the channel is completely open. It
is possible to start sending messages on the channel before this point.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-channels-close-ev">channel.onclose</h5>
<div class="literalblock">
<div class="content">
<pre>channel.addEventListener("close", function(event, options) { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>An event triggered when the channel closes. This can happen either
because <a href="#cockpit-channels-close">channel.close()</a> function was
called, or if the peer closed the channel, or the underlying transport
closes.</p>
</div>
<div class="paragraph">
<p>The <code>options</code> will contain various close information, including a
<code>"problem"</code> field which will be set if the channel was closed because
of a problem.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-transport-origin">cockpit.transport.origin</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.transport.origin</pre>
</div>
</div>
<div class="paragraph">
<p>The HTTP origin that is being used by the underlying channel transport.
This is read-only, you should not assign a value. If the browser
supports <code>window.location.origin</code> then this will be identical to that
value.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-transport-host">cockpit.transport.host</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.transport.host</pre>
</div>
</div>
<div class="paragraph">
<p>The host that this transport is going to talk to by default. This is
read-only, you should not assign a value. If the value is null that
means that the transport has not been setup yet.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-transport-csrf-token">cockpit.transport.csrf_token</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.transport.csrf_token</pre>
</div>
</div>
<div class="paragraph">
<p>A cross site request forgery token for use with external channels. This
becomes valid once the connection is properly established.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-transport-options">cockpit.transport.options</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.transport.options</pre>
</div>
</div>
<div class="paragraph">
<p>Initialization options received over the underlying channel transport.
These will be empty until connection is properly established.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-transport-wait">cockpit.transport.wait()</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.transport.wait(callback)</pre>
</div>
</div>
<div class="paragraph">
<p>Call the <code>callback</code> function once the underlying channel transport is
initialized. This will start the initialization if not already in
progress or completed. If the channel transport is already initialized,
then <code>callback</code> will be called immediately.</p>
</div>
<div class="paragraph">
<p>In general it&#8217;s not necessary to wait for the transport before starting
to open channels.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-transport-close">cockpit.transport.close()</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.transport.close([problem])</pre>
</div>
</div>
<div class="paragraph">
<p>Close the underlying channel transport. All channels open channels will
close. The <code>problem</code> argument should be a problem code string. If not
specified it will default to <code>"disconnected"</code>.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-transport-filter">cockpit.transport.filter()</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.transport.filter((message, channelid, control) =&gt;  { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>Add a filter to the underlying channel transport. All incoming messages
will be passed to each of the filter callbacks that are registered.</p>
</div>
<div class="paragraph">
<p>This function is rarely used.</p>
</div>
<div class="paragraph">
<p>Filter callbacks are called in the order they are registered. If a
filter callback returns <code>false</code> then the message will not be
dispatched further, whether to other filters, or to channels, etc.</p>
</div>
<div class="paragraph">
<p>The <code>message</code> is the string or array with the raw message including,
the framing. The <code>channelid</code> is the channel identifier or an empty
string for control messages. If <code>control</code> is set then this is a
control message,d and the <code>control</code> argument contains the parsed JSON
object of the control message.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-transport-inject">cockpit.transport.inject()</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.transport.inject(message, [out])</pre>
</div>
</div>
<div class="paragraph">
<p>Inject a message into the underlying channel transport. The <code>message</code>
should be a <code>string</code> or an array of bytes, and should be valid
according to the Cockpit message protocol. If the <code>out</code> argument is
equal to <code>false</code> then the message will be injected as an incoming
message as if it was received on the underlying channel transport.</p>
</div>
<div class="paragraph">
<p>This function is rarely used. In general you should only <code>inject()</code>
messages you got from a <code>filter()</code>.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-base64-encode">cockpit.base64_encode()</h5>
<div class="literalblock">
<div class="content">
<pre>string = cockpit.base64_encode(data)</pre>
</div>
</div>
<div class="paragraph">
<p>Encode binary data into a string using the Base64 encoding. The <code>data</code>
argument can either be a <code>string</code>, an <code>Array</code>, an <code>ArrayBuffer</code> or
a <code>Uint8Array</code>. The return value is a string.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-base64-decode">cockpit.base64_decode()</h5>
<div class="literalblock">
<div class="content">
<pre>data = cockpit.base64_decode(string, [constructor])</pre>
</div>
</div>
<div class="paragraph">
<p>Decode binary data from a Base64 encoded string. The <code>string</code> argument
should be a javascript string. The returned <code>data</code>&gt; will be an array
of bytes.</p>
</div>
<div class="paragraph">
<p>You can pass <code>Uint8Array</code>, <code>Array</code> or <code>String</code> as an alternate
<code>constructor</code> if you want the decoded data in an alternate form. The
default is to return an <code>Array</code>. Note that if you use a <code>String</code> for
the decoded data, then you must guarantee that the data does not contain
bytes that would be invalid for a string.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_dbus_client">cockpit.js: DBus Client</h4>
<div class="paragraph">
<p>Cockpit allows access to DBus services via this API.</p>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-types">DBus Types</h5>
<div class="paragraph">
<p>DBus values are represented as javascript values and objects as follows:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>BYTE 'y'</code></dt>
<dd>
<p>Javascript number.</p>
</dd>
<dt class="hdlist1"><code>BOOLEAN 'b'</code></dt>
<dd>
<p>Javascript boolean.</p>
</dd>
<dt class="hdlist1"><code>INT16 'n'</code></dt>
<dd>
<p>Javascript number.</p>
</dd>
<dt class="hdlist1"><code>UINT16 'q'</code></dt>
<dd>
<p>Javascript number.</p>
</dd>
<dt class="hdlist1"><code>INT32 'i'</code></dt>
<dd>
<p>Javascript number.</p>
</dd>
<dt class="hdlist1"><code>UINT32 'u'</code></dt>
<dd>
<p>Javascript number.</p>
</dd>
<dt class="hdlist1"><code>INT64 'x'</code></dt>
<dd>
<p>Javascript number.</p>
</dd>
<dt class="hdlist1"><code>UINT64 't'</code></dt>
<dd>
<p>Javascript number.</p>
</dd>
<dt class="hdlist1"><code>DOUBLE 'd'</code></dt>
<dd>
<p>Javascript number.</p>
</dd>
<dt class="hdlist1"><code>STRING 's'</code></dt>
<dd>
<p>Javascript string.</p>
</dd>
<dt class="hdlist1"><code>OBJECT_PATH 'o'</code></dt>
<dd>
<p>Javascript string.</p>
</dd>
<dt class="hdlist1"><code>SIGNATURE 'g'</code></dt>
<dd>
<p>Javascript string.</p>
</dd>
<dt class="hdlist1"><code>ARRAY of BYTE 'ay'</code></dt>
<dd>
<p>A string containing base64 encoded data.</p>
</dd>
<dt class="hdlist1"><code>ARRAY of DICT_ENTRY with STRING keys 'a{s?}'</code></dt>
<dd>
<p>A javascript plain object with the keys as property names.</p>
</dd>
<dt class="hdlist1"><code>ARRAY of DICT_ENTRY with other keys 'a{??}'</code></dt>
<dd>
<p>A javascript plain object each key JSON encoded into a string property
name.</p>
</dd>
<dt class="hdlist1"><code>ARRAY of other</code></dt>
<dd>
<p>A javascript array.</p>
</dd>
<dt class="hdlist1"><code>VARIANT</code></dt>
<dd>
<p>A javascript plain object with the <code>"t"</code> property set to a DBus type
string, and the <code>"v"</code> property set to a value.</p>
</dd>
<dt class="hdlist1"><code>HANDLE 'h'</code></dt>
<dd>
<p>A javascript object that describes a cockpit channel which represents
the passed file descriptor. The <code>payload</code> is always set to
<code>stream</code>. Pass it to
<a href="#cockpit-channels-channel">cockpit.channel()</a> to create the
channel and start reading or writing on it. Handles can only be
received, not sent from within cockpit.</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-dbus">cockpit.dbus()</h5>
<div class="literalblock">
<div class="content">
<pre>client = cockpit.dbus(name, [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Create a DBus client for the given bus <code>name</code> (eg: service name). Use
the following functions to make DBus method calls, watch for events,
etc. The optional <code>options</code> argument is a javascript plain object, and
may include:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>"bus"</code></dt>
<dd>
<p>The DBus bus to connect to. Specifying <code>"session"</code> will connect to
the DBus user session bus, <code>"user"</code> will connect to the user bus (on
some systems this is identical to the session bus), <code>"system"</code> will
connect to the DBus system bus, and <code>"none"</code> to the non-standard bus
specified with the <code>address</code> option. This defaults to "system" if
not present.</p>
</dd>
<dt class="hdlist1"><code>"address"</code></dt>
<dd>
<p>The bus address to connect to in case <code>bus</code> is <code>"none"</code>.</p>
</dd>
<dt class="hdlist1"><code>"superuser"</code></dt>
<dd>
<p>Set to <code>"require"</code> to talk to this service as root. The DBus service
will see the DBus method calls and accesses as coming from root,
rather than the logged in user. This is useful for talking to services
that do not correctly use
<a href="https://www.freedesktop.org/software/polkit">polkit</a> to authorize
administrative users. If the currently logged in user is not permitted
to become root (eg: via <code>pkexec</code>) then the <code>client</code> will
immediately be <a href="#cockpit-dbus-onclose">closed</a> with a
<code>"access-denied"</code> problem code.
+
Set to <code>"try"</code> to try to talk as root, but if that fails, fall back
to unprivileged.</p>
</dd>
<dt class="hdlist1"><code>"track"</code></dt>
<dd>
<p>It is valid for a DBus service to exit, and be restarted in such a way
that clients continue to talk to it across the restart. Some services
are not written with this in mind. If the <code>"track"</code> option is set to
<code>true</code> then the channel will close when the service exits and/or
disconnects from the DBus bus.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>If the <code>name</code> argument is null, and no options other than <code>"bus"</code>
are specified, then a shared DBus <code>client</code> is created. When using such
a client with a DBus bus, a <code>"name"</code> option must be specified on
various other methods in order to specify which client to talk to.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-wait">client.wait()</h5>
<div class="literalblock">
<div class="content">
<pre>promise = client.wait([callback])</pre>
</div>
</div>
<div class="paragraph">
<p>Returns a <code>promise</code> that is ready when the client is ready, or fails
if the client closes. If a <code>callback</code> is specified, it is attached to
the promise.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-close">client.close()</h5>
<div class="literalblock">
<div class="content">
<pre>client.close([problem])</pre>
</div>
</div>
<div class="paragraph">
<p>Close the DBus client. If <code>problem</code> is specified it should be a
<a href="#cockpit-problems">problem code</a> string.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-onclose">client.onclose</h5>
<div class="literalblock">
<div class="content">
<pre>client.addEventListener("close", options =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>An event triggered when the DBus client closes. This can happen either
because <a href="#cockpit-dbus-close">client.close()</a> function was called, or
the DBus service went away, or some other problem or disconnection.</p>
</div>
<div class="paragraph">
<p>The <code>options</code> will contain various close information, including a
<code>"problem"</code> field which will be set if the channel was closed because
of a problem.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-onowned">client.onowner</h5>
<div class="literalblock">
<div class="content">
<pre>client.addEventListener("owner", (event, owner) =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>An event triggered when the owner of the DBus name changes. The owner
value will be the id of the name owner on the bus or null if the name is
unowned. The absence of an owner should not be treated as a
disconnection. However this makes it possible to take some action based
on the actual status of the service, for example disconnecting a pending
signal handler.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-options">client.options</h5>
<div class="paragraph">
<p>Set to the options used when creating the client. Will not change for
the life of the client.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-unique-name">client.unique_name</h5>
<div class="paragraph">
<p>The unique DBus name of the client. Initially null, and becomes valid
once the the client is ready.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxy">client.proxy()</h5>
<div class="literalblock">
<div class="content">
<pre>proxy = client.proxy([interface, path], [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Create proxy javascript object for a DBus <code>interface</code>. At the
specified DBus object <code>path</code>. The proxy will have properties, methods
and signals from to the DBus interface, and allows for natural
interaction. If no <code>interface</code> is specified then the DBus bus name of
the client is used. If no <code>path</code> is specified, then the DBus name of
the client is converted to a path.</p>
</div>
<div class="paragraph">
<p>If creating lots of proxies for a given <code>interface</code> it is more
efficient to use the <a href="#cockpit-dbus-proxies"><code>client.proxies()</code></a>
function.</p>
</div>
<div class="paragraph">
<p>The proxy is loaded when the
<a href="#cockpit-dbus-proxy-valid"><code>proxy.valid</code></a> field is <code>true</code>, and
it is set to <code>false</code> if the underlying <code>interface</code> and/or <code>path</code>
don&#8217;t or no longer exist, or the <code>client</code> has closed. You can wait for
proxy to become valid by passing a callback to its
<a href="#cockpit-dbus-proxy-wait"><code>proxy.wait()</code></a> function. The
<a href="#cockpit-dbus-proxy-onchanged"><code>proxy.onchanged</code></a> event will also
fire when the proxy becomes valid or invalid. DBus properties and
methods on the proxy are not defined until the proxy becomes valid.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>value = proxy.Prop1
proxy.WritableProp = value</pre>
</div>
</div>
<div class="paragraph">
<p>All DBus properties on the <code>interface</code> that start with an upper case
letter (as is convention) will be automatically defined on this proxy,
and will update their values as the DBus property values change. In
addition the <a href="#cockpit-dbus-proxy-onchanged"><code>proxy.onchanged</code></a>
event will fire every time the properties change.</p>
</div>
<div class="paragraph">
<p>If you assign a value to a writable property on the proxy, the proxy
will try to set that property on the DBus <code>interface</code> at <code>path</code>. The
actual proxy property value will not update until the DBus service has
notified the proxy of the change. If setting a property fails a warning
will be logged. In order to have more reliable setting of properties, or
track when they have been set, or if setting fails, use the
<a href="#cockpit-dbus-call"><code>client.call()</code></a> directly. It should be noted
that DBus service implementations may also be inconsistent in their
behavior when setting a property fails.</p>
</div>
<div class="paragraph">
<p>You can access the raw property data using the
<a href="#cockpit-dbus-proxy-data"><code>proxy.data</code></a> field, including data for
properties that do not start with an upper case letter.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>proxy.Method(arg1, arg2)
    .then((retval1, retval2) =&gt; {
        ...
    })
    .catch(ex =&gt; {
        ...
    });</pre>
</div>
</div>
<div class="paragraph">
<p>All DBus methods on the <code>interface</code> that start with an upper case
letter (as is convention) will be automatically defined on this proxy.
These methods are called with arguments as normal javascript arguments.
A
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
that will complete successfully when the method returns, or fail if an
error occurs. The return values from the DBus method will be passed to
the <code>then</code> handler function directly.</p>
</div>
<div class="paragraph">
<p>Methods that do not start with an upper case letter can be invoked by
using the usual <a href="#cockpit-dbus-proxy-call"><code>proxy.call()</code></a>
directly.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>proxy.addEventListener("signal", (event, arg1, arg2) =&gt; {
    ...
});</pre>
</div>
</div>
<div class="paragraph">
<p>All DBus signals on the <code>interface</code> that start with an upper case
letter (as is convention) will be automatically emit events on this
proxy. These events will contain the signal arguments after the standard
<code>event</code> argument.</p>
</div>
<div class="paragraph">
<p>Signals that do not start with an upper case letter can be subscribed to
by using <a href="#cockpit-dbus-proxy-signal"><code>proxy.onsignal</code></a> directly.</p>
</div>
<div class="paragraph">
<p>Usually a proxy asks the <code>client</code> to watch and notify it of changes to
the relevant object or path. You can pass an <code>options</code> argument with
the <code>watch</code> field set to <code>false</code> to prevent this.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxy-client">proxy.client</h5>
<div class="paragraph">
<p>Set to the DBus client of the proxy. Will not change for the life of the
proxy.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxy-path">proxy.path</h5>
<div class="paragraph">
<p>Set to the DBus object path of the proxy. Will not change for the life
of the proxy.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxy-iface">proxy.iface</h5>
<div class="paragraph">
<p>Set to the DBus interface name of the proxy. Will not change for the
life of the proxy.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxy-valid">proxy.valid</h5>
<div class="paragraph">
<p>Set to <code>true</code> when the proxy&#8217;s DBus interface is present at its DBus
path, and all information for the proxy has loaded. Is set to <code>false</code>
while loading, and after the proxy no longer refers a DBus interface and
path. Also set to <code>false</code> if the <code>client</code> closes.</p>
</div>
<div class="paragraph">
<p>Use the by <a href="#cockpit-dbus-proxy-wait"><code>proxy.wait()</code></a> function to
wait for a proxy to load. The
<a href="#cockpit-dbus-proxy-onchanged"><code>proxy.onchanged</code></a> event will also
be emitted when the proxy becomes valid or invalid. DBus properties and
methods on the proxy are not defined until the proxy becomes valid.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxy-data">proxy.data</h5>
<div class="paragraph">
<p>A plain javascript object containing all the raw property data that this
proxy has loaded. This will be updated automatically as the proxy is
notified of property changes from the DBus service. The
<a href="#cockpit-dbus-proxy-onchanged"><code>proxy.onchanged</code></a> event will be
emitted when it changes.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxy-call">proxy.call()</h5>
<div class="literalblock">
<div class="content">
<pre>invocation = proxy.call(method, args, [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Make a DBus method call on this proxy.</p>
</div>
<div class="paragraph">
<p>For DBus methods that start with an upper case letter, is usually more
convenient <a href="#cockpit-dbus-proxy">to call the method directly on the
proxy</a>. However if methods that do not follow the usual DBus convention,
or specify additional options, or the caller cannot be sure that the
method actually exists, you can use this method.</p>
</div>
<div class="paragraph">
<p>This function also works on proxies that have are still loading and have
not become valid yet.</p>
</div>
<div class="paragraph">
<p>The <code>method</code> should be a DBus method name, and the <code>args</code> should be
an array of arguments to pass to the method. The <code>options</code> are
<a href="#cockpit-dbus-call">described elsewhere</a>.</p>
</div>
<div class="paragraph">
<p>The returned value is identical to the one returned from
<a href="#cockpit-dbus-call">client.call()</a>. It is a
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
that will complete successfully when the method returns, or fail if an
error occurs.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxy-wait">proxy.wait()</h5>
<div class="literalblock">
<div class="content">
<pre>promise = proxy.wait()
proxy.wait(() =&gt; {
    ...
});</pre>
</div>
</div>
<div class="paragraph">
<p>Wait for a proxy to finish loading. This function returns a promise. If
a callback function is passed as an argument then that function will be
invoked when the proxy is ready. If this method is called after a proxy
has already loaded, then the promise will be resolved immediately, and
any callback will be invoked immediately. Use the promise or
<code>proxy.valid</code> to determine whether the proxy is valid.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxy-onchanged">proxy.onchanged</h5>
<div class="literalblock">
<div class="content">
<pre>proxy.addEventListener("changed", (event, data) =&gt; {
    ...
});</pre>
</div>
</div>
<div class="paragraph">
<p>This event is emitted when the proxy&#8217;s properties change.</p>
</div>
<div class="paragraph">
<p>The <code>data</code> has the following form, and will only include properties
that have changed:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{
    "Prop1": "value",
    "Prop2": 5
}</pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxy-signal">proxy.onsignal</h5>
<div class="literalblock">
<div class="content">
<pre>proxy.addEventListener("signal", (event, name, args) =&gt; {
    ...
});</pre>
</div>
</div>
<div class="paragraph">
<p>This event is emitted when the proxy&#8217;s emits an event.</p>
</div>
<div class="paragraph">
<p>For most events, that have names which start with an upper case letter,
you can just <a href="#cockpit-dbus-proxy">connect to that event as a signal
directly</a>. However if you wish to be notified when any signal is
emitted, or for signals that do not follow the usual DBus convention,
you can connect to this event.</p>
</div>
<div class="paragraph">
<p>The <code>name</code> is the DBus signal name, and the <code>args</code> is an array of
arguments that were emitted with the signal.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxies">client.proxies()</h5>
<div class="literalblock">
<div class="content">
<pre>proxies = client.proxies([interface], [path_namespace], [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Create <a href="#cockpit-dbus-proxy">proxy javascript objects</a> for a DBus
interfaces. The proxies will have properties, methods and signals from
the DBus <code>interface</code>, and allow for natural interaction. If no
<code>interface</code> is specified then the DBus bus name of the client is used.
If no <code>path_namespace</code> is provided then <code>"/"</code> will be used.</p>
</div>
<div class="paragraph">
<p>Proxies will be automatically created for instances of the <code>interface</code>
available at the DBus service. The optional <code>path_namespace</code> argument
can be used to restrict the proxies for instances that have DBus paths
which have the namespace path prefix.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>proxy1 = proxies["/dbus/path1"];
proxy2 = proxies["/dbus/path2"];
for (proxy in proxies) {
    ...
}</pre>
</div>
</div>
<div class="paragraph">
<p>The returned <code>proxies</code> object will is used as a dictionary, and will
have values containing proxies for DBus interface instances, with the
keys being the DBus paths of those instances. It is possible to
enumerate over the returned <code>proxies</code>.</p>
</div>
<div class="paragraph">
<p>Proxies will be automatically added and removed from the <code>proxies</code>
object as they appear and disappear in the service. The
<a href="#cockpit-dbus-proxies-onadded"><code>proxies.onadded</code></a> and
<a href="#cockpit-dbus-proxies-onremoved"><code>proxies.onremoved</code></a> events will
be emitted. DBus services may not support notifications of paths
disappearing.</p>
</div>
<div class="paragraph">
<p>Use the <code>proxies.wait()</code> function to be notified when the initial set
of proxies has been populated.</p>
</div>
<div class="paragraph">
<p>Usually a proxies ask the <code>client</code> to watch and be notified of changes
to the relevant object or path. You can pass an <code>options</code> argument
with the <code>watch</code> field set to <code>false</code> to prevent this.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxies-wait">proxies.wait()</h5>
<div class="literalblock">
<div class="content">
<pre>promise = proxies.wait()
proxies.wait(() =&gt; {
    ...
});</pre>
</div>
</div>
<div class="paragraph">
<p>Wait for a <code>proxies</code> object to populate its initial set of proxies.
This function returns a promise. If a callback function is passed as an
argument then that function will be invoked when the proxies are ready.
If this method is called after the proxies have populated, then the
promise will be resolved immediately, and any callback will be invoked
immediately.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxies-client">proxies.client</h5>
<div class="paragraph">
<p>Set to the DBus client of the proxies. Will not change.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxies-iface">proxies.iface</h5>
<div class="paragraph">
<p>Set to the DBus interface name of the proxies. Will not change.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxies-path_namespace">proxies.path_namespace</h5>
<div class="paragraph">
<p>Set to the DBus path namespace used which the proxies must have as a
DBus path prefix. Will not change.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxies-onadded">proxies.onadded</h5>
<div class="literalblock">
<div class="content">
<pre>proxies.addEventListener("added", (event, proxy) =&gt; {
    ...
})</pre>
</div>
</div>
<div class="paragraph">
<p>This event is emitted when a proxy is added to the <code>proxies</code> object.
The proxy will already have loaded.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxies-onchanged">proxies.onchanged</h5>
<div class="literalblock">
<div class="content">
<pre>proxies.addEventListener("changed", (event, proxy) =&gt; {
    ...
})</pre>
</div>
</div>
<div class="paragraph">
<p>This event is emitted when one of the proxy in the <code>proxies</code> object
changes its properties.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-proxies-onremoved">proxies.onremoved</h5>
<div class="literalblock">
<div class="content">
<pre>proxies.addEventListener("removed", (event, proxy) =&gt; {
    ...
})</pre>
</div>
</div>
<div class="paragraph">
<p>This event is emitted when a proxy is removed to the <code>proxies</code> object.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-call">client.call()</h5>
<div class="literalblock">
<div class="content">
<pre>invocation = client.call(path, interface, method, args, [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Make a DBus method call.</p>
</div>
<div class="paragraph">
<p>The <code>path</code> is the DBus object path to make the call on, <code>interface</code>
is the DBus interface for the method and <code>method</code> is the name of the
method to call. The <code>args</code> is an array of arguments to pass to the
method, each of which must be appropriate for the expected
<a href="#cockpit-dbus">DBus type</a> of that argument. The <code>args</code> may be
<code>null</code> if no arguments are to be sent.</p>
</div>
<div class="paragraph">
<p>The returned value is a
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
that will complete successfully when the method returns, or fail if an
error occurs.</p>
</div>
<div class="paragraph">
<p>If <code>options</code> is specified it should be a plain javascript object,
which may contain the following properties:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>flags</code></dt>
<dd>
<p>A string containing DBus message flags. The character <code>"i"</code>
indicates to the dbus service that interactive authentication is
allowed. If the entire <code>flags</code> field is missing, then <code>"i"</code> is set
by default.</p>
</dd>
<dt class="hdlist1"><code>type</code></dt>
<dd>
<p>A valid DBus type signature to use when calling the method. In the
absence of this, the DBus service will be introspected (and the result
cached) to ask what the method type signature is.</p>
</dd>
<dt class="hdlist1"><code>timeout</code></dt>
<dd>
<p>The timeout of the call in milliseconds. The call will fail with the
<code>"timeout"</code> problem code. If "timeout" is not given, the call will
never time out.</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-then">invocation.then()</h5>
<div class="literalblock">
<div class="content">
<pre>invocation.then((args, options) =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This is a standard
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
method. It sets up a handler to be called when the DBus method call
finishes successfully.</p>
</div>
<div class="paragraph">
<p>The <code>args</code> argument is an array of return values from the DBus method.
Each of them will be converted to an appropriate
<a href="#cockpit-dbus">javascript type</a>.</p>
</div>
<div class="paragraph">
<p>The <code>options</code> argument may contain additional information about the
reply. If the <code>type</code> option was specified when performing the method
call, then the <code>options</code> in the reply here will also contain a
<code>type</code> field containing the DBus type signature of the output. If the
<code>flags</code> option was specified when performing the call then the
<code>options</code> in the reply here will contain message flags. Possible out
message flags are:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>&gt;</code></dt>
<dd>
<p>A big endian message.</p>
</dd>
<dt class="hdlist1"><code>&lt;</code></dt>
<dd>
<p>A little endian message.</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-catch">invocation.catch()</h5>
<div class="literalblock">
<div class="content">
<pre>invocation.catch(exception =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This is a standard
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
method. It sets up a handler to be called when the DBus method call
fails.</p>
</div>
<div class="paragraph">
<p>The <code>exception</code> object passed to the handler can have the following
properties:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>problem</code></dt>
<dd>
<p>A <a href="#cockpit-problems">problem code</a> string when a problem occurred
starting or communicating with the DBus service. This is <code>null</code> in
the cases where an actual DBus error was occurred.</p>
</dd>
<dt class="hdlist1"><code>name</code></dt>
<dd>
<p>The DBus error name. This will be <code>null</code> in cases where the failure
was not due to a DBus error.</p>
</dd>
<dt class="hdlist1"><code>message</code></dt>
<dd>
<p>A DBus error message. This will be <code>null</code> in cases where the failure
was not due to a DBus error.</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-subscribe">client.subscribe()</h5>
<div class="literalblock">
<div class="content">
<pre>subscription = client.subscribe(match, (path, interface, signal, args) =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>Subscribe to signals. The <code>match</code> argument is a javascript plain
object which defines what signals to subscribe to. Each property in the
<code>match</code> argument restricts signals subscribed to. If a property is not
present then it is treated as a wildcard, matching anything. If an empty
object is specified as <code>match</code> then all signals will be subscribed to.
The <code>match</code> argument may contain the following properties:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>interface</code></dt>
<dd>
<p>A DBus interface to match.</p>
</dd>
<dt class="hdlist1"><code>path</code></dt>
<dd>
<p>A DBus object path to match. May not be used together with the
<code>path_namespace</code> property. It should be a valid DBus object path,
that is, it should have no trailing slash.</p>
</dd>
<dt class="hdlist1"><code>path_namespace</code></dt>
<dd>
<p>A DBus object path prefix to match. Any paths in the hierarchy below
this top path will match. May not be used together with the <code>path</code>
property.</p>
</dd>
<dt class="hdlist1"><code>member</code></dt>
<dd>
<p>The DBus signal name to match.</p>
</dd>
<dt class="hdlist1"><code>arg0</code></dt>
<dd>
<p>Matches the first argument of a DBus message, which must be a string.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The handler passed as the second argument will be invoked when the
signal is received. A <code>subscription</code> is returned which can be used to
remove the subscription by calling its <code>subscription.remove()</code> method.</p>
</div>
<div class="paragraph">
<p>It is not a problem to subscribe to the same signals more than once,
with identical or slightly different <code>match</code> arguments.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-remove">subscription.remove()</h5>
<div class="literalblock">
<div class="content">
<pre>subscription.remove()</pre>
</div>
</div>
<div class="paragraph">
<p>Unsubscribe from the DBus signal subscription.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-watch">client.watch()</h5>
<div class="literalblock">
<div class="content">
<pre>watch = client.watch(path)
watch = client.watch({ "path_namespace": path_namespace, "interface": interface })</pre>
</div>
</div>
<div class="paragraph">
<p>Watch for property and interface changes on the given DBus object
<code>path</code> DBus <code>path_namespace</code>. If <code>interface</code> is specified only
properties on that DBus interface will be watched.</p>
</div>
<div class="paragraph">
<p>The <a href="#cockpit-dbus-proxy"><code>client.proxy()</code></a> and
<a href="#cockpit-dbus-proxies"><code>client.proxies()</code></a> functions and the
objects they return are high level wrappers around <code>client.watch()</code>.</p>
</div>
<div class="paragraph">
<p>The property and interface changes will be available in raw form on the
<a href="#cockpit-dbus-onnotify"><code>client.onnotify</code></a> event.</p>
</div>
<div class="paragraph">
<p>Property and interface changes that are caused by a method call or
signal will show up before that method call reply is received, or signal
event is triggered. It should be possible to rely on this guarantee,
unless the DBus service in question behaves incorrectly. Internally
these watches work well with code that implements the
<a href="https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">ObjectManager</a>
portion of the DBus specification. If no ObjectManager implementation is
available, the watch falls back to using DBus
<a href="https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-introspectable">Introspection</a>
along with the usual
<a href="https://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">PropertiesChanged</a>
signal. If the DBus service implements none of these, or implements them
in an inconsistent manner, then this function will provide inconsistent
or unexpected results.</p>
</div>
<div class="paragraph">
<p>The parameter is either a DBus <code>path</code> or a plain javascript object
with zero or more of the following fields. If an empty javascript object
is used as an argument, then all paths, interfaces and properties will
be watched.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>interface</code></dt>
<dd>
<p>Watch properties on this DBus interface.</p>
</dd>
<dt class="hdlist1"><code>path</code></dt>
<dd>
<p>Watch interfaces and properties at this DBus path. May not be used
together with the <code>path_namespace</code> property.</p>
</dd>
<dt class="hdlist1"><code>path_namespace</code></dt>
<dd>
<p>Watch interfaces and properties under this DBus path. It should be a
valid DBus object path, that is, it should have no trailing slash. If
an ObjectManager implementation is available at this interface, then
it is used. May not be used together with the <code>path</code> property.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The returned value is a
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
that will complete successfully when the watch has populated its initial
set of properties and interfaces, and these have been notified via
<a href="#cockpit-dbus-onnotify"><code>client.onnotify</code></a>.</p>
</div>
<div class="paragraph">
<p>A watch can be removed by calling the
<a href="#cockpit-dbus-watch-remove"><code>watch.remove()</code></a> method on the
returned value. If identical watches are added more than once, then they
must also be removed the same number of times before the removal takes
effect.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-watch-then">watch.then()</h5>
<div class="literalblock">
<div class="content">
<pre>watch.then(() =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This is a standard
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
method. It sets up a handler to be called when the watch has populated
its initial properties and interfaces.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-watch-catch">watch.catch()</h5>
<div class="literalblock">
<div class="content">
<pre>watch.catch(ex =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This is a standard
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
method. It sets up a handler to be called if the watch fails to populate
its initial properties and interfaces. Note that a watch will only fail
if the DBus client closes or is somehow disconnected. It does not fail
in the case of missing interfaces or properties.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-watch-remove">watch.remove()</h5>
<div class="literalblock">
<div class="content">
<pre>watch.remove()</pre>
</div>
</div>
<div class="paragraph">
<p>Remove the watch. This may not have any immediate effect if other
watches are in place. In particular, if identical watches are added more
than once, then they must also be removed the same number of times
before the removal takes effect.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-onnotify">client.onnotify</h5>
<div class="literalblock">
<div class="content">
<pre>client.addEventListener("notify", data =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>An event triggered when <a href="#cockpit-dbus-watch">watched</a> properties or
interfaces change.</p>
</div>
<div class="paragraph">
<p>The <a href="#cockpit-dbus-proxy"><code>client.proxy()</code></a> and
<a href="#cockpit-dbus-proxies"><code>client.proxies()</code></a> functions and the
objects they return are high level wrappers around the <code>data</code> provided
by this event.</p>
</div>
<div class="paragraph">
<p>The <code>data</code> has the following form:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>{
    "/path1": {
        "org.Interface1": {
            "Prop1": "value",
            "Prop2": 5
        },
        "org.Interface2": null
    }
}</pre>
</div>
</div>
<div class="paragraph">
<p>Multiple paths may be present, each of which may have multiple
interfaces, each of which may have multiple properties. The first time a
given path and interface is emitted from this signal, it will have all
its properties and interfaces. Thereafter only changes are noted. If an
interface is set to <code>null</code>, then that interface has disappeared.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-notify">client.notify()</h5>
<div class="literalblock">
<div class="content">
<pre>client.notify(data)</pre>
</div>
</div>
<div class="paragraph">
<p>Emits a synthetic <a href="#cockpit-dbus-onnotify"><code>notify</code></a> event. The
<code>data</code> argument should follow the same layout as described for the
<code>notify</code> event.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-onmeta">client.onmeta</h5>
<div class="literalblock">
<div class="content">
<pre>client.onmeta = (ev, data) =&gt; { ... }</pre>
</div>
</div>
<div class="paragraph">
<p>An event triggered when the meta data about
<a href="#cockpit-dbus-watch">watched</a> interfaces is loaded.</p>
</div>
<div class="paragraph">
<p>The <a href="#cockpit-dbus-proxy"><code>client.proxy()</code></a> and
<a href="#cockpit-dbus-proxies"><code>client.proxies()</code></a> functions and the
objects they return are high level wrappers around the <code>data</code> provided
by this event.</p>
</div>
<div class="paragraph">
<p>The <code>data</code> has the following form:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>  {
      "org.Interface": {
          "methods": {
              "Method1": {
                  "in": [ "s", "v" ],
                  "out": [ "i" ]
              },
              "Method2": { }
          },
          "signals": {
              "Signal": {
                  "in": [ "b", "s" ]
              }
          },
          "properties": {
              "Prop1": {
                  "flags": "rw",
                  "type": "s"
              },
              "Prop2": {
                  "flags": "r",
                  "type": "b"
              }
          }
      }
  }</pre>
</div>
</div>
<div class="paragraph">
<p>Multiple interfaces may be present, each of which may have methods and
properties. This is emitted before the first
<a href="#cockpit-dbus-proxy"><code>client.onnotify</code></a> event for the relevant
interface.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-dbus-variant">cockpit.variant()</h5>
<div class="literalblock">
<div class="content">
<pre>variant = cockpit.variant(type, value)</pre>
</div>
</div>
<div class="paragraph">
<p>A DBus variant is represented as a plain javascript object with a
<code>"t"</code> property represesting the full DBus type of the variant, and a
<code>"v"</code> property containing the variant value.</p>
</div>
<div class="paragraph">
<p>This is a helper function for creating such a variant object.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_errors">cockpit.js: Errors</h4>
<div class="paragraph">
<p>cockpit.js: Errors</p>
</div>
<div class="paragraph">
<p>Problem codes and messages</p>
</div>
<div class="sect4">
<h5 id="cockpit-problems">Problem Codes</h5>
<div class="paragraph">
<p>Cockpit represents problems with standardized problem string codes.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>"access-denied"</code></dt>
<dd>
<p>The user is not permitted to perform the action in question.</p>
</dd>
<dt class="hdlist1"><code>"authentication-failed"</code></dt>
<dd>
<p>User authentication failed.</p>
</dd>
<dt class="hdlist1"><code>"internal-error"</code></dt>
<dd>
<p>An unexpected internal error without further info. This should not
happen during the normal course of operations.</p>
</dd>
<dt class="hdlist1"><code>"no-cockpit"</code></dt>
<dd>
<p>The system does not have a compatible version of Cockpit installed or
installed properly.</p>
</dd>
<dt class="hdlist1"><code>"no-session"</code></dt>
<dd>
<p>Cockpit is not logged in.</p>
</dd>
<dt class="hdlist1"><code>"not-found"</code></dt>
<dd>
<p>Something specifically requested was not found, such as a file,
executable etc.</p>
</dd>
<dt class="hdlist1"><code>"terminated"</code></dt>
<dd>
<p>Something was terminated forcibly, such as a connection, process
session, etc.</p>
</dd>
<dt class="hdlist1"><code>"timeout"</code></dt>
<dd>
<p>Something timed out.</p>
</dd>
<dt class="hdlist1"><code>"unknown-hostkey"</code></dt>
<dd>
<p>The remote host had an unexpected or unknown key.</p>
</dd>
<dt class="hdlist1"><code>"no-forwarding"</code></dt>
<dd>
<p>Could not forward authentication credentials to the remote host.</p>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-messages">cockpit.message()</h5>
<div class="literalblock">
<div class="content">
<pre>message = cockpit.message(problem)
message = cockpit.message(exception)</pre>
</div>
</div>
<div class="paragraph">
<p>Return a message for the <code>exception</code> or <code>problem</code> code passed as an
argument. If the argument is an object with a <code>"message"</code> property, as
is the case with most exceptions, that will be returned directly. If the
argument is an object with a <code>"problem"</code> property, then it will be
used as the problem code. An appropriate message will be returned for
problem codes.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_file_access">cockpit.js: File Access</h4>
<div class="paragraph">
<p>The <code>cockpit.file</code> API lets you read, write, and watch regular files
in their entirety. It cannot efficiently do random access in a big file
or read non-regular files such as <code>/dev/random</code>.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>file = cockpit.file(path,
                    { syntax: syntax_object,
                      binary: boolean,
                      max_read_size: int,
                      superuser: string,
                    })

promise = file.read()
promise
    .then((content, tag) =&gt; { ... })
    .catch(error =&gt; { ... })

promise = file.replace(content, [ expected_tag ])
promise
    .then(new_tag =&gt; { ... })
    .catch(error =&gt; { ... })

promise = file.modify(callback, [ initial_content, initial_tag ]
promise
    .then((new_content, new_tag) =&gt; { ... })
    .catch(error =&gt; { ... })

file.watch((content, tag, [error]) =&gt; { }, [ { read: boolean } ])

file.close()</pre>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-file-simple">Simple reading and writing</h5>
<div class="paragraph">
<p>You can read a file with code like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cockpit.file("/path/to/file").read()
    .then((content, tag) =&gt; {
        ...
    })
    .catch(error =&gt; {
        ...
    });</pre>
</div>
</div>
<div class="paragraph">
<p>It is recommended to use absolute paths. Relative paths are resolved
against <code>/</code>. To work with the current user&#8217;s files
<a href="#cockpit-user">cockpit.user()</a> can be used to get the user&#8217;s home
directory.</p>
</div>
<div class="paragraph">
<p>The <code>read()</code> method returns a
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>.</p>
</div>
<div class="paragraph">
<p>When successful, the promise will be resolved with the content of the
file. Unless you specify options to change this (see below), the file is
assumed to be text in the UTF-8 encoding, and <code>content</code> will be a
string.</p>
</div>
<div class="paragraph">
<p>The tag that is passed to the <code>then()</code> callback is a short string that
is associated with the file and changes whenever the content of the file
changes. It is meant to be used with <code>replace()</code>.</p>
</div>
<div class="paragraph">
<p>It is not an error when the file does not exist. In this case, the
<code>then()</code> callback will be called with a <code>null</code> value for <code>content</code>
and <code>tag</code> is <code>"-"</code>.</p>
</div>
<div class="paragraph">
<p>The <code>superuser</code> option can be used the same way as described in the
<a href="#cockpit-channels-channel">cockpit.channel()</a> to provide a different
access level to the file.</p>
</div>
<div class="paragraph">
<p>You can use the <code>max_read_size</code> option to limit the amount of data
that is read. If the file is larger than the given number of bytes, no
data is read and the channel is closed with problem code <code>too-large</code>.
The default limit is 16 MiB. The limit can be completely removed by
setting it to -1.</p>
</div>
<div class="paragraph">
<p>To write to a file, use code like this:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cockpit.file("/path/to/file").replace("my new content\n")
    .then(tag =&gt; {
        ...
    })
    .catch(error =&gt; {
        ...
    });</pre>
</div>
</div>
<div class="paragraph">
<p>The <code>replace()</code> method returns a
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>.</p>
</div>
<div class="paragraph">
<p>When the promise is resolved, the file has been atomically replaced (via
the <code>rename()</code> syscall) with the new content. As with <code>read()</code>, by
default the new content is a string and will be written to the file as
UTF-8. The returned tag corresponds to the new content of the file.</p>
</div>
<div class="paragraph">
<p>When the promise is rejected because of an error, the file or its meta
data has not been changed in any way.</p>
</div>
<div class="paragraph">
<p>As a special case, passing the value <code>null</code> to <code>replace()</code> will
remove the file.</p>
</div>
<div class="paragraph">
<p>The <code>replace()</code> method can also check for conflicting changes to a
file. You can pass a tag (as returned by <code>read()</code> or <code>replace()</code>) to
<code>replace()</code>, and the file will only be replaced if it still has the
given tag. If the tag of the file has changed, <code>replace()</code> will fail
with an error object that has <code>error.problem == "change-conflict"</code>.
See <code>modify()</code> below for a convenient way to achieve transactional
updates to a file.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-file-format">File format</h5>
<div class="paragraph">
<p>By default, a file is assumed to be text encoded in UTF-8, and the
<code>read()</code> and <code>replace()</code> functions use strings to represent the
content.</p>
</div>
<div class="paragraph">
<p>By specifying the <code>syntax.parser()</code> and <code>syntax.stringify()</code>
options, you can cause <code>read()</code> to parse the content before passing it
back to you, and <code>replace()</code> to unparse it before writing.</p>
</div>
<div class="paragraph">
<p>The main idea is to be able to write <code>{ syntax: JSON }</code>, of course,
but you can easily pass in individual functions or make your own
parser/unparser object:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>cockpit.file("/path/to/file.json", { syntax: JSON })

var syntax_object = {
    parse:     my_parser,
    stringify: my_unparser
};

cockpit.file("/path/to/file", { syntax: syntax_object })</pre>
</div>
</div>
<div class="paragraph">
<p>Any exceptions thrown by the <code>parse()</code> and <code>stringify()</code> functions
are caught and reported as read or write errors.</p>
</div>
<div class="paragraph">
<p>The <code>null</code> value that is used to represent the content of a
non-existing file (see "Simple reading and writing", above) is not
passed through the <code>parse()</code> and <code>stringify()</code> functions.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-file-binary">Binary files</h5>
<div class="paragraph">
<p>By default the content of the file is assumed to be text encoded as
UTF-8 and it can not contain zero bytes. The content is represented as a
JavaScript string with <code>read()</code>, <code>replace()</code>, etc. By setting the
<code>binary</code> option to true when creating the proxy, no assumptions are
placed on the content, and it is represented as a <code>Uint8Array</code> in
JavaScript.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-file-atomic">Atomic modifications</h5>
<div class="paragraph">
<p>Use <code>modify()</code> to modify the content of the file safely. A call to
<code>modify()</code> will read the content of the file, call <code>callback</code> on the
content, and then replace the content of the file with the return value
of the callback.</p>
</div>
<div class="paragraph">
<p>The <code>modify()</code> method uses the <code>read()</code> and <code>replace()</code> methods
internally in the obvious way. Thus, the <code>syntax.parse()</code> and
<code>syntax.stringify()</code> options work as expected, <code>null</code> represents a
non-existing file, and the watch callbacks are fired.</p>
</div>
<div class="paragraph">
<p>It will do this one or more times, until no other conflicting changes
have been made to the file between reading and replacing it.</p>
</div>
<div class="paragraph">
<p>The callback is called like this</p>
</div>
<div class="literalblock">
<div class="content">
<pre>new_content = callback (old_content)</pre>
</div>
</div>
<div class="paragraph">
<p>The callback is allowed to mutate <code>old_content</code>, but note that this
will also mutate the objects that are passed to the watch callbacks.
Returning <code>undefined</code> from the proxy is the same as returning
<code>old_content</code>.</p>
</div>
<div class="paragraph">
<p>The <code>modify()</code> method returns a
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>.</p>
</div>
<div class="paragraph">
<p>The promise will be resolved with the new content and its tag, like so</p>
</div>
<div class="literalblock">
<div class="content">
<pre>function shout(old_content) {
    return old_content.toUpperCase();
}

cockpit.file("/path/to/file").modify(shout)
    .then((content, tag) =&gt; {
        ...
    })
    .catch(error =&gt; {
        ...
    });</pre>
</div>
</div>
<div class="paragraph">
<p>If you have cached the last content and tag results of the <code>read()</code> or
<code>modify()</code> method, or the last values passed to a watch callback, you
can pass them to <code>modify()</code> as the second and third argument. In this
case, <code>modify()</code> will skip the initial read and start with the given
values.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-file-notify">Change notifications</h5>
<div class="paragraph">
<p>Calling <code>watch()</code> will start monitoring the file for external changes.</p>
</div>
<div class="literalblock">
<div class="content">
<pre>handle = file.watch(callback);

handle_no_read = file.watch(callback, { read: false });</pre>
</div>
</div>
<div class="paragraph">
<p>Whenever a change occurs, the <code>callback()</code> is called with the new
content and tag of the file. This might happen because of external
changes, but also as part of calls to <code>read()</code>, <code>replace()</code>, and
<code>modify()</code>.</p>
</div>
<div class="paragraph">
<p>When a read error occurs, the <code>callback()</code> is called with an error as
a third argument. Write errors are not reported via the watch callback.</p>
</div>
<div class="paragraph">
<p>Calling <code>watch()</code> will also automatically call <code>read()</code> to get the
initial content of the file. Thus, you normally don&#8217;t need to call
<code>read()</code> at all when using <code>watch()</code>.</p>
</div>
<div class="paragraph">
<p>To disable the automatic reading, e.g. for large files or unreadable
file system objects, set the <code>read</code> option to <code>false</code>. The first
<code>content</code> argument of the callback will then always be <code>null</code>.</p>
</div>
<div class="paragraph">
<p>To free the resources used for monitoring, call <code>handle.remove()</code>.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-file-path">file.path</h5>
<div class="paragraph">
<p>A string containing the path that was passed to the <code>cockpit.file()</code>
method.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-file-close">Closing</h5>
<div class="paragraph">
<p>Call the <code>close()</code> method on a file proxy to cancel all ongoing
operations, such as reading, writing, and monitoring. The proxy should
not be used after closing it.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_http_client">cockpit.js: HTTP Client</h4>
<div class="paragraph">
<p>Cockpit allows access to local HTTP and REST services via this API.</p>
</div>
<div class="sect4">
<h5 id="cockpit-http-constructor">cockpit.http()</h5>
<div class="literalblock">
<div class="content">
<pre>http = cockpit.http(endpoint, [options])
http = cockpit.http(options)</pre>
</div>
</div>
<div class="paragraph">
<p>Create a new HTTP client. The <code>endpoint</code> can be a file path starting
with <code>/</code> to connect to a unix socket, or it can be a port number to
connect to. The optional <code>options</code> argument is a javascript plain
object, and may include:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>"address"</code></dt>
<dd>
<p>Connect to an address other than localhost. Must be a valid host name
or IP address. To use this option you also must provide a port number.</p>
</dd>
<dt class="hdlist1"><code>"port"</code></dt>
<dd>
<p>Port number to use with "address" option, when not given in
<code>endpoint</code>.</p>
</dd>
<dt class="hdlist1"><code>"tls"</code></dt>
<dd>
<p>Object properties for an https connection. See
<code>http-stream2 TLS options</code>.</p>
</dd>
<dt class="hdlist1"><code>"headers"</code></dt>
<dd>
<p>Additional HTTP headers to include with the HTTP request. This is a
plain javascript object with each key as a header name, and each value
as the header value.</p>
</dd>
<dt class="hdlist1"><code>"superuser"</code></dt>
<dd>
<p>Set to <code>"require"</code> to open this channel as root. If the currently
logged in user is not permitted to become root (eg: via <code>pkexec</code>)
then the <code>channel</code> will immediately be
<a href="#cockpit-channels-close-ev">closed</a> with a <code>"access-denied"</code>
problem code.
+
Set to <code>"try"</code> to try to make the request as root, but if that
fails, fall back to perform an unprivileged request.</p>
</dd>
<dt class="hdlist1"><code>"tls"</code></dt>
<dd>
<p>If set to a plain javascript object, then the connection will be an
HTTPS connection and include TLS encryption. The fields of the <code>tls</code>
object declare various TLS configuration and data. All fields are
optional:
+</p>
<div class="ulist">
<ul>
<li>
<p><code>"authority"</code>: Certificate authority(s) to expect as signers of
the server&#8217;s TLS certificate, represented as a plain javascript
object. It should have either a <code>"file"</code> field containing a readable
PEM file on the system containing authorities, or a <code>"data"</code> with
PEM encoded certificate data.</p>
</li>
<li>
<p><code>"certificate"</code>: A client certificate to use, represented as a
plain javascript object. It should have either a <code>"file"</code> field
containing a readable PEM file on the system to use as a certificate,
or a <code>"data"</code> with PEM encoded certificate data.</p>
</li>
<li>
<p><code>"key"</code>: A client key to use, represented as a plain javascript
object. It should have either a <code>"file"</code> field containing a readable
PEM file on the system to use as a key, or a <code>"data"</code> with PEM
encoded key data.</p>
</li>
<li>
<p><code>"validate"</code>: A boolean that describes whether to validate the
server&#8217;s TLS certificate or not. By default local connections are not
validated, and remote connections are validated.</p>
</li>
</ul>
</div>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Here is a somewhat complex example of using most of the above
<code>options</code> when when calling <code>cockpit.http()</code>:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>http = cockpit.http({
    "address": "localhost",
    "headers": {
        "Authorization": "Basic dXNlcjpwYXNzd29yZA=="
    },
    "port": 443,
    "tls": {
        "validate": true,
        "authority": {
            "file": "/etc/pki/tls/certs/ca-bundle.crt",
        },
        "certificate": {
            "data": "-----BEGIN CERTIFICATE-----\nMIIDsDCCA..."
        },
        "key": {
            "data": "-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBA..."
        }
    }
});</pre>
</div>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-http-get">http.get()</h5>
<div class="literalblock">
<div class="content">
<pre>request = http.get(path, [params, [headers]])</pre>
</div>
</div>
<div class="paragraph">
<p>Perform an HTTP GET request for the given <code>path</code>. If the <code>params</code> is
specified it should be a plain javascript object, which will be turned
into a query string.</p>
</div>
<div class="paragraph">
<p>Optionally a plain javascript object containing headers can be included
in the <code>headers</code> argument.</p>
</div>
<div class="paragraph">
<p>The return value is a
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
that will complete if the request happens successfully, or fail if
there&#8217;s a problem.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-http-post">http.post()</h5>
<div class="literalblock">
<div class="content">
<pre>request = http.post(path, body, [headers])</pre>
</div>
</div>
<div class="paragraph">
<p>Perform an HTTP POST request for the given <code>path</code>. The <code>body</code> can be
a string, or a javascript plain object, which will be encoded as JSON
data. If <code>body</code> is <code>undefined</code> or <code>null</code> then an empty HTTP body
will be sent.</p>
</div>
<div class="paragraph">
<p>Optionally a plain javascript object containing headers can be included
in the <code>headers</code> argument.</p>
</div>
<div class="paragraph">
<p>The return value is a
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
that will complete if the request happens successfully, or fail if
there&#8217;s a problem.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-http-request">http.request()</h5>
<div class="literalblock">
<div class="content">
<pre>request = http.request(options)</pre>
</div>
</div>
<div class="paragraph">
<p>Perform an HTTP request. The <code>options</code> can contain the following:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>"body"</code></dt>
<dd>
<p>The HTTP request body. If you do not specify a body, then you must
call <a href="#cockpit-http-input">request.input()</a> to complete the body
and allow the request to start.</p>
</dd>
<dt class="hdlist1"><code>"headers"</code></dt>
<dd>
<p>A javascript plain object containing HTTP headers.</p>
</dd>
<dt class="hdlist1"><code>"method"</code></dt>
<dd>
<p>The HTTP method. Defaults to <code>"GET"</code>.</p>
</dd>
<dt class="hdlist1"><code>"params"</code></dt>
<dd>
<p>A javascript plain object containing query string parameters.</p>
</dd>
<dt class="hdlist1"><code>"path"</code></dt>
<dd>
<p>The HTTP path. Defaults to <code>/</code>.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The return value is a
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
that will complete if the request happens successfully, or fail if
there&#8217;s a problem.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-http-then">request.then()</h5>
<div class="literalblock">
<div class="content">
<pre>request.then(data =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This is a standard
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
method. It sets up a handler to be called when the request finishes
successfully.</p>
</div>
<div class="paragraph">
<p>The <code>data</code> argument contains the body result of the request. If it a
string, unless the process was opened in binary mode, in which case the
<code>data</code> is an array of bytes. If a <code>request.stream()</code> handler is set
up, then any standard output data consumed by the handler will not be
included in the <code>data</code> argument.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-http-catch">request.catch()</h5>
<div class="literalblock">
<div class="content">
<pre>request.catch((exception[, data]) =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This is a standard
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
method. It sets up a handler to be called when the request fails, or
returns an error code.</p>
</div>
<div class="paragraph">
<p>The <code>exception</code> object passed to the handler can have the following
fields:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>problem</code></dt>
<dd>
<p>A <a href="#cockpit-problems">problem code</a> string when a problem occurred
starting or communicating with the server. This is <code>null</code> if the
process exited or was terminated.</p>
</dd>
<dt class="hdlist1"><code>status</code></dt>
<dd>
<p>The numeric status of the response. This is <code>null</code> if no response
was received.</p>
</dd>
<dt class="hdlist1"><code>reason</code></dt>
<dd>
<p>A string reason returned in the response. This is <code>null</code> if no
response was received.</p>
</dd>
<dt class="hdlist1"><code>message</code></dt>
<dd>
<p>A string message returned in the response. This is <code>null</code> if no
response was received.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>If the request returned a response body, it will be available in the
<code>data</code> argument. Otherwise this argument will be <code>undefined</code>.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-http-response">request.response()</h5>
<div class="literalblock">
<div class="content">
<pre>request.response((status, headers) =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This sets up a handler to be called when the HTTP request gets the
initial response from the server. The <code>status</code> argument is the HTTP
status integer, and the <code>headers</code> is a plain javascript object
containing the headers of the response.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-http-stream">request.stream()</h5>
<div class="literalblock">
<div class="content">
<pre>request.stream(data =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This sets up a handler to be called when the request returns output
data. The handler will be called multiple times.</p>
</div>
<div class="paragraph">
<p>Only one handler may be registered at a time. Registering an additional
handler replaces the previous one. The handler receives either string
<code>data</code> or an array of binary bytes as its argument. A stream handler
may return a number, which indicates the number of characters or bytes
consumed from <code>data</code>. Any data not consumed will be included again the
next time the handler is called.</p>
</div>
<div class="paragraph">
<p>If a <code>request.stream()</code> handler is set up, then the <code>request.then()</code>
handlers will only get any remaining data not consumed by the stream
handler.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-http-input">request.input()</h5>
<div class="literalblock">
<div class="content">
<pre>request.input(data, [stream])</pre>
</div>
</div>
<div class="paragraph">
<p>This method writes <code>data</code> to the HTTP request body. It is only valid
if no <code>"body"</code> has been specified in
<a href="#cockpit-http-request">http.request()</a> options. If <code>stream</code> is
<code>true</code> then this function can be called again to provide further data.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-http-close">request.close()</h5>
<div class="literalblock">
<div class="content">
<pre>request.close([problem])</pre>
</div>
</div>
<div class="paragraph">
<p>Cancel the request. If <code>problem</code> is specified it should be a standard
<a href="#cockpit-problems">problem code</a> string.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-http-close-all">http.close()</h5>
<div class="literalblock">
<div class="content">
<pre>http.close([problem])</pre>
</div>
</div>
<div class="paragraph">
<p>Cancel all outstanding requests with the given problem code. This is
useful when you know that the server is going down soon.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_localization">cockpit.js: Localization</h4>
<div class="paragraph">
<p>Cockpit provides a <a href="https://www.gnu.org/software/gettext/"><code>gettext()</code></a>
like API for easy translation of strings.</p>
</div>
<div class="sect4">
<h5 id="cockpit-locale-language">cockpit.language</h5>
<div class="paragraph">
<p>The current locale language code. This is set based on the
<a href="#cockpit-locale-locale"><code>cockpit.locale()</code></a> data loaded.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-locale-locale">cockpit.locale()</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.locale(po)</pre>
</div>
</div>
<div class="paragraph">
<p>Load locale information for a given <code>po</code> data. The data should be JSON
data in the <a href="https://www.npmjs.org/package/po2json">po2json</a> format. The
data will be loaded globally. If <code>po</code> data has already been loaded,
then this will extend that loaded data with additional strings. Any
identical translations strings will be replaced with the new strings. A
<code>null</code> argument clears all the locale information previously loaded.</p>
</div>
<div class="paragraph">
<p>Various methods such as
<a href="#cockpit-locale-gettext"><code>cockpit.gettext()</code></a> make use of the
loaded data.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-locale-gettext">cockpit.gettext()</h5>
<div class="literalblock">
<div class="content">
<pre>translated = cockpit.gettext([context], string)
var _ = cockpit.gettext
var C_ = cockpit.gettext
translated = _("string")
translated = C_("context", "string")</pre>
</div>
</div>
<div class="paragraph">
<p>Lookup <code>string</code> for translation in the loaded locale data. The
translated string will be returned, or <code>string</code> will be returned if no
such translated string is present. The <code>context</code> argument is an
optional string used to qualify the string.</p>
</div>
<div class="paragraph">
<p>This function can be assigned to a variable called <code>_</code> (underscore)
which will make your code work with the typical <code>_("string")</code> syntax.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-locale-noop">cockpit.noop()</h5>
<div class="literalblock">
<div class="content">
<pre>var N_ = cockpit.noop
var NC_ = cockpit.noop</pre>
</div>
</div>
<div class="paragraph">
<p>A noop function suitable for assigning to <code>N_</code> or <code>NC_</code> so that
gettext scanners will be able to find translatable strings. More
specifically this function returns its last argument.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-locale-ngettext">cockpit.ngettext()</h5>
<div class="literalblock">
<div class="content">
<pre>translated = cockpit.ngettext([context], string1, stringN, number)</pre>
</div>
</div>
<div class="paragraph">
<p>Lookup a string appropriate for a pluralization form of the <code>number</code>.
Various languages have complex pluralization forms that go far between
the singular and plural forms speakers of English are familiar with. If
no such translated string is found then either one of <code>string1</code> or
<code>stringN</code> is returned according to simple pluralization rules.</p>
</div>
<div class="paragraph">
<p>The <code>context</code> argument is an optional string used to qualify the
string.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-locale-translate">cockpit.translate()</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.translate()
cockpit.translate(element, ...)
cockpit.translate(selection)</pre>
</div>
</div>
<div class="paragraph">
<p>The document will be scanned for <code>translate</code> tags and they will be
translated according to the strings in loaded locale data. One or more
<code>element</code> arguments may be specified. These are DOM elements for
specific parts of the document to be translated. If no <code>element</code> is
specified then the entire document is translated.</p>
</div>
<div class="paragraph">
<p>If an array or array-like object is passed as a <code>selection</code> then all
DOM elements in the array will be treated as parts of the document to be
translated.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_page_location_and_jumping">cockpit.js: Page Location and Jumping</h4>
<div class="paragraph">
<p>Page location and navigation between components</p>
</div>
<div class="sect4">
<h5 id="cockpit-location-general">Page location</h5>
<div class="literalblock">
<div class="content">
<pre>location = cockpit.location
cockpit.location = "/path"</pre>
</div>
</div>
<div class="paragraph">
<p>Cockpit components often have different views, without changing the HTML
file that is being viewed. These are known as pages.
<code>cockpit.location</code> is an object that can be used to read the current
page and to navigate to a different page location. It works by updating
<code>window.location.hash</code>.</p>
</div>
<div class="paragraph">
<p>The <code>cockpit.location</code> looks like a HTTP path with a possible query
string:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>/path/sub/page?option=value,option2</pre>
</div>
</div>
<div class="paragraph">
<p>The <a href="#cockpit-location-path"><code>location.path</code></a> and
<a href="#cockpit-location-options"><code>location.options</code></a> contain a parsed
form of the location. While the location cannot be modified in place, a
new one can be created by assigning a string to <code>cockpit.location</code> or
by calling the <a href="#cockpit-location-go"><code>location.go()</code></a> function.</p>
</div>
<div class="paragraph">
<p><code>cockpit.location</code> is designed similarly to <code>window.location</code> in
that the location object is preplaced whenever the current page location
changes. To be aware of when the page location changes listen for the
<a href="#cockpit-location-changed"><code>cockpit.onlocationchanged</code></a> event.</p>
</div>
<div class="paragraph">
<p>Using the location object as a string will result in the
<a href="#cockpit-location-href"><code>location.href</code></a>.</p>
</div>
<div class="sect5">
<h6 id="cockpit-location-href">location.href</h6>
<div class="paragraph">
<p>The string representation of this page location, including any options.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-location-path">location.path</h6>
<div class="paragraph">
<p>An array of path segments, parsed and decoded appropriately. An empty
array denotes the root path.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-location-options">location.options</h6>
<div class="paragraph">
<p>A javascript object containing the various options present in the
location.</p>
</div>
<div class="paragraph">
<p>If an option appears more than once, its value will be an array.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-location-go">location.go()</h6>
<div class="literalblock">
<div class="content">
<pre>location.go(path, [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Changes the current location to the given <code>path</code> and <code>options</code>. If
the <code>path</code> argument is a string, it will be parsed into a path. If it
is a relative path, then the result will be relative to the current
<code>location.path</code>. If the <code>path</code> argument is an array of path
segments, it will be treated as a full parsed absolute path.</p>
</div>
<div class="paragraph">
<p>Any options found in a <code>path</code> will be added to those in the optional
<code>options</code> argument, and used in the result.</p>
</div>
<div class="paragraph">
<p>The location change will only take effect if the location has not
changed in the meantime. This can be to good effect by saving a
<code>cockpit.location</code> object and doing a conditional navigation, by
calling the saved <code>location.go()</code> method later. This will only
navigate if the user or other code has not navigated in the meantime.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-location-replace">location.replace()</h6>
<div class="literalblock">
<div class="content">
<pre>location.replace(path, [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Similar to <a href="#cockpit-location-go"><code>location.go()</code></a> except the
location change will not result in a navigation change in the browser&#8217;s
history.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-location-decode">location.decode()</h6>
<div class="literalblock">
<div class="content">
<pre>path = location.decode(href, [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Decode a cockpit href into its <code>path</code> array. If the <code>options</code>
argument is specified, then it will be populated with options found in
the href.</p>
</div>
<div class="paragraph">
<p>If href is a relative path it will be resolved relative to
<code>location.href</code>.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-location-encode">location.encode()</h6>
<div class="literalblock">
<div class="content">
<pre>href = location.encode(path, [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Encode the given <code>path</code> and <code>options</code> into a cockpit href. The
<code>path</code> argument may be an array of path segments, or a string path. If
a relative path is passed, it will be resolved relative to
<code>location.href</code>.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-location-changed">cockpit.onlocationchanged</h6>
<div class="literalblock">
<div class="content">
<pre>cockpit.addEventListener("locationchanged", function() { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>An event emitted when over the <code>cockpit.location</code> changes. Typically a
component reacts to this event by updating its interface to reflect the
new <a href="#cockpit-location-path"><code>cockpit.location.path</code></a> and
<a href="#cockpit-location-options"><code>cockpit.location.options</code></a>.</p>
</div>
<div class="paragraph">
<p>This event is not triggered immediately during a <code>location.go()</code> or
similar call. It will be triggered asynchronously at a later time.</p>
</div>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-jump">Jumping between components</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.jump("/system/log")</pre>
</div>
</div>
<div class="paragraph">
<p>In Cockpit in there multiple components shown. In order to tell Cockpit
to jump to and show another component and a certain location within that
component, use the <code>cockpit.jump()</code> function. Stable component paths
are documented. Don&#8217;t assume you can navigate into paths that are not
stable API.</p>
</div>
<div class="sect5">
<h6 id="cockpit-jump-jump">cockpit.jump()</h6>
<div class="literalblock">
<div class="content">
<pre>cockpit.jump(path, [ host ])</pre>
</div>
</div>
<div class="paragraph">
<p>Ask Cockpit to jump to another component. The location of the current
component will not be affected. The <code>path</code> argument can be a string
path, starting with <code>/</code> or an array containing the parts of a path
that will be joined to create a path. If <code>host</code> is not specified, then
the component on the same host as the caller will be displayed. If host
is null, then the host portion of the path will be removed, displaying
the component on the host that cockpit is connected directly to.</p>
</div>
<div class="paragraph">
<p>If the calling component is not running within Cockpit, or the calling
component is not currently displayed, then the jump will not happen, and
this function has no effect.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-jump-hidden">cockpit.hidden</h6>
<div class="paragraph">
<p>A boolean property that indicates if the current component page is
visible or hidden. When the code or user jumps to another component, the
prior one remains loaded and initialized but is hidden. Use this
property together with the
<a href="#cockpit-jump-visibilitychange"><code>cockpit.onvisibilitychange</code></a>
event to decide whether or not to perform expensive tasks to update the
interface.</p>
</div>
<div class="paragraph">
<p>This property is analogous to the <code>document.hidden</code> page visibility
API, but works with the document and frame implementation of Cockpit.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-jump-visibilitychange">cockpit.onvisibilitychange</h6>
<div class="literalblock">
<div class="content">
<pre>cockpit.onvisibilitychange = function() { ... }</pre>
</div>
</div>
<div class="paragraph">
<p>This event is emitted when the
<a href="#cockpit-jump-hidden"><code>cockpit.hidden</code></a> property changes. This
event is similar to the <code>document.onvisibilitychange</code> API, but works
with the document and frame implementation of Cockpit.</p>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_user_session">cockpit.js: User Session</h4>
<div class="paragraph">
<p>User information and login session state</p>
</div>
<div class="sect4">
<h5 id="cockpit-logout">cockpit.logout()</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.logout([reload])</pre>
</div>
</div>
<div class="paragraph">
<p>Logout of Cockpit. Unless <code>reload</code> is <code>false</code> this will also cause
the page to be reloaded, so that the user can see the logged out state.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-user">cockpit.user()</h5>
<div class="literalblock">
<div class="content">
<pre>var promise = cockpit.user();
promise.then(user =&gt; { ... });</pre>
</div>
</div>
<div class="paragraph">
<p>This object contains information about the user that&#8217;s currently logged
into cockpit. The following fields are defined:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>"id"</code></dt>
<dd>
<p>This is unix user id.</p>
</dd>
<dt class="hdlist1"><code>"gid"</code></dt>
<dd>
<p>This is unix user group id.</p>
</dd>
<dt class="hdlist1"><code>"name"</code></dt>
<dd>
<p>This is the unix user name like <code>"root"</code>.</p>
</dd>
<dt class="hdlist1"><code>"full_name"</code></dt>
<dd>
<p>This is a readable name for the user.</p>
</dd>
<dt class="hdlist1"><code>"groups"</code></dt>
<dd>
<p>This is an array of group names to which the user belongs. Since
version 318, the first item in this list is the primary group.</p>
</dd>
<dt class="hdlist1"><code>"home"</code></dt>
<dd>
<p>This is user&#8217;s home directory.</p>
</dd>
<dt class="hdlist1"><code>"shell"</code></dt>
<dd>
<p>This is unix user shell.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>Returns a promise that completes once the user information is available.</p>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<div class="title">Warning</div>
</td>
<td class="content">
<div class="paragraph">
<p><code>cockpit.user()</code> is soft-deprecated since Cockpit 336, if your page
does not need to maintain compatibility with older Cockpit versions you
can use<a href="#cockpit-info">cockpit.info</a> to obtain the user information.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-permission">Permission lookup</h5>
<div class="paragraph">
<p>Cockpit provides a mechanism for checking if the current user satisfies
a given criteria. This is meant for updating UI elements based on what
actions the user can perform. It is <em>not an access control mechanism</em>.</p>
</div>
<div class="sect5">
<h6 id="cockpit-permission-constructor">cockpit.permission()</h6>
<div class="literalblock">
<div class="content">
<pre>permission = cockpit.permission([options])</pre>
</div>
</div>
<div class="paragraph">
<p>Create a new permission object to check if the current user has a
particular permission specified by <code>options</code>:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>admin: true</code></dt>
<dd>
<p>True if the session has superuser privileges, i.e. can run channels as
root with <code>{ superuser: "require" }</code>.</p>
</dd>
<dt class="hdlist1"><code>group:</code> <em>name</em></dt>
<dd>
<p>True if the currently logged user is a member of group <em>name</em>.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The permission result is always true for the "root" user. When
<code>options</code> is not given, check if the current user is root.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-permission-allowed">permission.allowed</h6>
<div class="paragraph">
<p>A boolean value which indicates if the permission is allowed or not.
This will be <code>null</code> if the permission is unknown, or there was an
error checking the permission or the permission data has not yet loaded.
This property will update asynchronously and if you wish to be notified
of changes connect to the
<a href="#cockpit-permission-changed">permission.onchanged</a> event.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-permission-changed">permission.onchanged</h6>
<div class="literalblock">
<div class="content">
<pre>permission.addEventListener("changed", function() { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This event is fired when the permission changes. In particular the
<a href="#cockpit-permission-allowed">permission.allowed</a> property.</p>
</div>
</div>
<div class="sect5">
<h6 id="cockpit-permission-close">permission.close()</h6>
<div class="literalblock">
<div class="content">
<pre>permission.close()</pre>
</div>
</div>
<div class="paragraph">
<p>Closes the permission object and tears down any registered callbacks and
dbus subscriptions.</p>
</div>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_manifests">cockpit.js: Manifests</h4>
<div class="sect4">
<h5 id="cockpit-manifest-loading">Loading Manifests</h5>
<div class="paragraph">
<p>For a convenient access to all page manifests, include
<code>&lt;script src="../manifests.js"&gt;&lt;/script&gt;</code> into your page to register
the manifests at the <code>cockpit.manifests</code> global variable.</p>
</div>
<div class="paragraph">
<p>You can also load <code>../manifests.json</code> directly in your page, with
<a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch"><code>fetch()</code></a>.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_metrics">cockpit.js: Metrics</h4>
<div class="paragraph">
<p>Metrics about the system can be retrieved from several sources using
<a href="#cockpit-metrics"><code>cockpit.metrics()</code></a> metrics channels. The
metrics are made available as series data, and can be used with the
<a href="#cockpit-series"><code>cockpit.series()</code></a> and
<a href="#cockpit-grid"><code>cockpit.grid()</code></a> facilities.</p>
</div>
<div class="sect4">
<h5 id="cockpit-metrics-function">cockpit.metrics()</h5>
<div class="literalblock">
<div class="content">
<pre>metrics = cockpit.metrics(interval, options, cache)</pre>
</div>
</div>
<div class="paragraph">
<p>Opens a new metrics channel. The data retrieved will be available in the
<a href="#cockpit-metrics-series"><code>metrics.series</code></a> series sink, and can be
used together with <a href="#cockpit-grid"><code>cockpit.grid()</code></a> objects.</p>
</div>
<div class="paragraph">
<p>The <code>interval</code> is in milliseconds, and is the granularity of the
series data retrieved. Any grids consuming the data must have the same
interval.</p>
</div>
<div class="paragraph">
<p>The <code>cache</code> argument is a cache identifier. If specified, then this
metrics channel will share data with other metrics channels of the same
identifier. Make sure to use a globally unique string.</p>
</div>
<div class="paragraph">
<p>The <code>options</code> argument is either a javascript plain object, or an
array of those. Each object can have the following fields.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>"metrics"</code></dt>
<dd>
<p>An array of full metric descriptions, as javascript objects. The
specifics of these, and how to determine which ones to use, can
unfortunately only be found in the low-level protocol documentation.
This option is required.</p>
</dd>
<dt class="hdlist1"><code>"source"</code></dt>
<dd>
<p>The source to use for real-time data. This is used by the <code>follow</code>
method, see below. Set to <code>"internal"</code> to retrieve internal metrics
read by the bridge. If set to <code>"direct"</code> or <code>"pmcd"</code> then data
will be retrieved from <a href="https://pcp.io">PCP</a>if it is available. The
default is <code>"internal"</code>.</p>
</dd>
<dt class="hdlist1"><code>"archive_source"</code></dt>
<dd>
<p>The source to use for retrieving historical data. This is used by the
<code>fetch</code> method, see below. Set to <code>"pcp-archive"</code> to retrieve data
from PCP archives. The default is not to try to retrieve historical
data.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>When the <code>options</code> argument is an array of javascript objects, then
the metrics channel tries to use them in order until one succeeds. This
way, you can prefer PCP as the source but fall back to internal metrics
when PCP is not available, for example. The channel gives no indication
which of the options has been used, and <code>fetch</code> and <code>follow</code> might
use different entries from the list.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-metrics-fetch">metrics.fetch()</h5>
<div class="literalblock">
<div class="content">
<pre>metrics.fetch(beg, end)</pre>
</div>
</div>
<div class="paragraph">
<p>Retrieve archived metrics data between <code>beg</code> and <code>end</code>. The
arguments can either be numbers, in which case they are interval based
offsets, or they can be javascript Date objects.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-metrics-follow">metrics.follow()</h5>
<div class="literalblock">
<div class="content">
<pre>metrics.follow()</pre>
</div>
</div>
<div class="paragraph">
<p>Start retrieving live metrics data as it become available.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-metrics-close">metrics.close()</h5>
<div class="literalblock">
<div class="content">
<pre>metrics.close()</pre>
</div>
</div>
<div class="paragraph">
<p>Stop the retrieval of metrics and release resources.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-metrics-series">metrics.series</h5>
<div class="paragraph">
<p>The series sink where data retrieved data will be processed.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-metrics-meta">metrics.meta</h5>
<div class="paragraph">
<p>The metrics meta data last received.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-metrics-onchanged">metrics.onchanged</h5>
<div class="literalblock">
<div class="content">
<pre>metrics.onchanged = function() { }</pre>
</div>
</div>
<div class="paragraph">
<p>An event triggered when one of the properties on this metrics object
changes.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_series_data">cockpit.js: Series Data</h4>
<div class="paragraph">
<p>Series data consists of values along a continuous (usually time) axis.
We can place these in grids which expose a distinct subset of these
values. These are the underlying mechanism for displaying metrics data
in graphs.</p>
</div>
<div class="sect4">
<h5 id="cockpit-grid">cockpit.grid()</h5>
<div class="literalblock">
<div class="content">
<pre>grid = cockpit.grid(interval, [beg, end])</pre>
</div>
</div>
<div class="paragraph">
<p>Creates a grid object to contain series data.</p>
</div>
<div class="paragraph">
<p>The <code>interval</code> is the granularity of the grid. Usually this is a
number of milliseconds, when used with time series data. The <code>beg</code> and
<code>end</code> are the bounds of the grid. If omitted they will be set to zero
for an initially empty grid.</p>
</div>
<div class="paragraph">
<p>If <code>beg</code> and/or <code>end</code> are negative (including negative zero) then
they are interpreted in number of intervals relative to the current
time. Thus cockpit.grid(1000, -300, -0) will create a grid for the most
recent 5 minutes.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-grid-add">grid.add()</h5>
<div class="literalblock">
<div class="content">
<pre>row = grid.add(series, path)
row = grid.add(callback, [early])
row = grid.add()</pre>
</div>
</div>
<div class="paragraph">
<p>Adds a row to the grid. The returned <code>row</code> is a Javascript array that
will contain series data. The arguments control how the row is populated
from the series data. The <code>row</code> is a sparse array. Its <code>row.length</code>
will not match the expected size of the grid, unless and until the row
has been completely filled in. The first index of the <code>row</code> will
contain the data from the series data at the
<a href="#cockpit-grid-beg"><code>grid.beg</code></a> offset.</p>
</div>
<div class="paragraph">
<p>When no arguments are passed, an empty row is added, and it is not
populated with data.</p>
</div>
<div class="paragraph">
<p>When called with a <code>series</code> and <code>path</code> argument then the row will be
populated directly with series data. The <code>series</code> can either be a
<a href="#cockpit-series">series object</a> or an object that has an
<code>obj.series</code> property. The <a href="#cockpit-series-interval">series
interval</a> must match the interval of this grid. If <code>path</code> is missing
or empty, then the series data is placed into the row directly.
Otherwise <code>path</code> indicates which part of the series data to place in
the row. When <code>path</code> is an array, it is used as a set of property
names or array indexes to follow into nested series data. When <code>path</code>
is a dotted string, it is split and used the same way to locate the
correct value in nested series data. The exact format of the series data
depends on its producer, and relevant paths will be documented there.</p>
</div>
<div class="paragraph">
<p>If a <code>callback</code> function is specified, then it will be invoked to
provide series data for the row. The function is invoked as
<code>callback(row, index, count)</code>, where the <code>row</code> is the row to fill
in, the <code>index</code> is the index to start filling in and <code>count</code> is the
number of items to fill in. The <code>this</code> variable will be set to the
grid while invoking the <code>callback</code>. The callback is called after other
data rows for a given series have been filled in. Callbacks are called
in the order added, unless the <code>early</code> argument is set to <code>true</code>, in
which case the callback is called earlier than callbacks without the
<code>early</code> argument set.</p>
</div>
<div class="paragraph">
<p>To remove the row use the <a href="#cockpit-grid-remove"><code>grid.remove()</code>
method.</a></p>
</div>
<div class="paragraph">
<p>The row will start being populated with data when the <code>series</code>
produces data. To make this happen right away, use the
<a href="#cockpit-grid-sync"><code>grid.sync()</code></a> method.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-grid-remove">grid.remove()</h5>
<div class="literalblock">
<div class="content">
<pre>grid.remove(row)</pre>
</div>
</div>
<div class="paragraph">
<p>Remove a previously added <code>row</code> from the grid. The row will no longer
be updated with series data.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-grid-sync">grid.sync()</h5>
<div class="literalblock">
<div class="content">
<pre>grid.sync()</pre>
</div>
</div>
<div class="paragraph">
<p>Load or reload data from the series into the rows. This does not clear
the rows before populating them. Some data may be populated immediately,
others may have to wait until data can be loaded. Internally this
function calls <a href="#cockpit-series-load"><code>series.load()</code></a> for each
series.</p>
</div>
<div class="paragraph">
<p>All rows with callbacks will be invoked to regenerate all the data. The
<a href="#cockpit-grid-onnotify"><code>grid.onnotify</code></a> event will be triggered.
It is not necessary to call this function after a call of the
<a href="#cockpit-grid-move"><code>grid.move()</code></a> method.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-grid-move">grid.move()</h5>
<div class="literalblock">
<div class="content">
<pre>grid.move(beg[, end])</pre>
</div>
</div>
<div class="paragraph">
<p>Move the grid to new <code>beg</code> and <code>end</code> range. Data will be discarded
from the rows and <a href="#cockpit-grid-sync"><code>grid.sync()</code></a> will be
called to load or reload series data for the new range of offsets.</p>
</div>
<div class="paragraph">
<p>If <code>end</code> is not specified it will be set to <code>beg</code>. If <code>beg</code> and/or
<code>end</code> are negative (including negative zero) then they will be set to
the number of intervals prior to the current time taken as an interval.</p>
</div>
<div class="paragraph">
<p>If <code>beg</code> and/or <code>end</code> are negative (including negative zero) then
they are interpreted in number of intervals relative to the current
time. Thus cockpit.grid(1000, -300, -0) will create a grid for the most
recent 5 minutes.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-grid-walk">grid.walk()</h5>
<div class="literalblock">
<div class="content">
<pre>grid.walk()</pre>
</div>
</div>
<div class="paragraph">
<p>Move the grid forward every
<a href="#cockpit-grid-interval"><code>grid.interval</code></a> milliseconds. To stop
moving forward, call <a href="#cockpit-grid-move"><code>grid.move()</code></a>.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-grid-notify">grid.notify()</h5>
<div class="literalblock">
<div class="content">
<pre>grid.notify(index, count)</pre>
</div>
</div>
<div class="paragraph">
<p>This function is called to have rows with callbacks recalculate their
data. It is not normally necessary to call this function, as it will be
invoked automatically when new series data is available or has been
loaded. This function triggers the
<a href="#cockpit-grid-onnotify"><code>grid.onnotify</code></a> event.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-grid-onnotify">grid.onnotify</h5>
<div class="literalblock">
<div class="content">
<pre>grid.addEventListener("notify", function(index, count) { ... });</pre>
</div>
</div>
<div class="paragraph">
<p>An event that is triggered when some part of the series data in grid
changes. The <code>index</code> is the row index where things changed, and the
<code>count</code> is the length of the data that changed.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-grid-close">grid.close()</h5>
<div class="literalblock">
<div class="content">
<pre>grid.close()</pre>
</div>
</div>
<div class="paragraph">
<p>Close the grid, and stop updating the rows.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-grid-interval">grid.interval</h5>
<div class="paragraph">
<p>The granularity of the grid. For time series data this is an interval in
milliseconds. In order to use a given <a href="#cockpit-grid">grid</a> and
<a href="#cockpit-series">series</a> together, their interval properties must
match.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-grid-beg">grid.beg</h5>
<div class="paragraph">
<p>The beginning offset of the series data in the grid. Do not set this
property directly. Use the <a href="#cockpit-grid-move">grid.move()</a> method
instead.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-grid-end">grid.end</h5>
<div class="paragraph">
<p>The ending offset of the series data in the grid. Do not set this
property directly. Use the <a href="#cockpit-grid-move">grid.move()</a> method
instead.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-series">cockpit.series()</h5>
<div class="literalblock">
<div class="content">
<pre>series = cockpit.series(interval, [cache, fetch])</pre>
</div>
</div>
<div class="paragraph">
<p>Create a new sink of series data. This is usually done by producers of
series data, and it is rare to invoke this function directly.</p>
</div>
<div class="paragraph">
<p>The <code>interval</code> is the granularity of the series data. For time series
data this is an interval in milliseconds. If a <code>cache</code> string is
specified, series data will be cached across frames for series with the
same <code>cache</code> cache identifier to load and/or reload.</p>
</div>
<div class="paragraph">
<p>If a <code>fetch</code> callback is specified, then it will be invoked when grids
request certain ranges of data. The <code>fetch</code> callback is invoked with
<code>function fetch(beg, end) { ... }</code> range offsets. The
<a href="#cockpit-series-input">series.input()</a> should be called with data
retrieved, either immediately or at a later time. The callback may be
called multiple times for the same ranges of data. It is up to the
callback to determine when or whether it should retrieve the data more
than once.</p>
</div>
<div class="paragraph">
<p>A producer of series data, usually calls this function and creates
itself a <code>obj.series</code> property containing this series object.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-series-input">series.input()</h5>
<div class="literalblock">
<div class="content">
<pre>series.input(beg, items[, mapping])</pre>
</div>
</div>
<div class="paragraph">
<p>Send series data into the series sink. Any grids that have added rows
based on this series, will have data filled in. The <code>beg</code> is the
beginning offset of <code>items</code>. The <code>items</code> are an array one or more
series data items.</p>
</div>
<div class="paragraph">
<p>Producers may wish to provide additional properties that can be used in
lookup paths that rows can pull from. This is done in the <code>mapping</code>
argument. If specified it is a tree of objects. Each sub object should
have a property with the name <code>""</code> empty string, which will be used as
the property name or index in place of the one used in the lookup path.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-series-load">series.load()</h5>
<div class="literalblock">
<div class="content">
<pre>series.load(beg, end)</pre>
</div>
</div>
<div class="paragraph">
<p>Load data from the series into any grids that have rows based on this
series data. Any cached data will be filled in immediately. Any data not
cached, will be requested from the producer, if possible, and may arrive
at a later time.</p>
</div>
<div class="paragraph">
<p>The <code>beg</code> and <code>end</code> denote the range of data to load.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-series-interval">series.interval</h5>
<div class="paragraph">
<p>The granularity of the series. For time series data this is an interval
in milliseconds. In order to use a given <a href="#cockpit-grid">grid</a> and
<a href="#cockpit-series">series</a> together, their interval properties must
match.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-series-limit">series.limit</h5>
<div class="paragraph">
<p>The maximum number of items to cache for loading and/or reloading. You
can change this value to a different number. Having a number close to
zero will break certain usage of grids, such as
<a href="#cockpit-grid-walk"><code>grid.walk()</code></a>.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_spawning_processes">cockpit.js: Spawning Processes</h4>
<div class="paragraph">
<p>This is the API for spawning a process and receiving its output, as well
as exit codes.</p>
</div>
<div class="sect4">
<h5 id="cockpit-spawn-spawn">cockpit.spawn()</h5>
<div class="literalblock">
<div class="content">
<pre>process = cockpit.spawn(args, [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Spawns a process on the system.</p>
</div>
<div class="paragraph">
<p>The <code>args</code> should be an array starting with the executable and
containing all the arguments to pass on the command line. If <code>args</code> is
a string then it is interpreted as an executable name. The optional
<code>options</code> argument is a javascript plain object and can contain any of
the following fields:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>"binary"</code></dt>
<dd>
<p>If set to <code>true</code> then handle the input and output of the process as
arrays of binary bytes.</p>
</dd>
<dt class="hdlist1"><code>"directory"</code></dt>
<dd>
<p>The directory to spawn the process in.</p>
</dd>
<dt class="hdlist1"><code>"err"</code></dt>
<dd>
<p>Controls where the standard error is sent. By default it is logged to
the journal. If set to <code>"out"</code> it is included in with the output
data. If set to <code>"ignore"</code> then the error output is discarded. If
set to <code>"message"</code>, then it will be returned as the error message.
When the <code>"pty"</code> field is set, this field has no effect.</p>
</dd>
<dt class="hdlist1"><code>"environ"</code></dt>
<dd>
<p>An optional array that contains strings to be used as additional
environment variables for the new process. These are <code>"NAME=VALUE"</code>
strings.</p>
</dd>
<dt class="hdlist1"><code>"pty"</code></dt>
<dd>
<p>Launch the process in its own PTY terminal, and send/receive terminal
input and output.</p>
</dd>
<dt class="hdlist1"><code>"batch"</code></dt>
<dd>
<p>Batch data coming from the process in blocks of at least this size.
This is not a guarantee. After a short timeout the data will be sent
even if the data doesn&#8217;t match the batch size. Defaults to zero.</p>
</dd>
<dt class="hdlist1"><code>"latency"</code></dt>
<dd>
<p>The timeout for flushing any cached data in milliseconds.</p>
</dd>
<dt class="hdlist1"><code>"superuser"</code></dt>
<dd>
<p>Set to <code>"require"</code> to spawn the process as root instead of the
logged in user. If the currently logged in user is not permitted to
become root (eg: via <code>pkexec</code>) then the <code>client</code> will immediately
be <a href="#cockpit-dbus-onclose">closed</a> with a <code>"access-denied"</code>
problem code.
+
Set to <code>"try"</code> to try to run the process as root, but if that fails,
fall back to an unprivileged process.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>The spawned process is a
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">promise</a>
that will complete if the process exits successfully, or fail if there&#8217;s
a problem. Some additional methods besides the standard promise methods
are documented below.</p>
</div>
<div class="paragraph">
<p>The standard output of the process is made available via the spawned
process object. Any non-UTF8 output from the process will be coerced
into textual form. It is highly recommended that only textual output be
produced by the command. The standard error is logged to the journal.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-spawn-script">cockpit.script()</h5>
<div class="literalblock">
<div class="content">
<pre>process = cockpit.script(script, [args], [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Run a shell script on the system.</p>
</div>
<div class="paragraph">
<p>This function <a href="#cockpit-spawn-spawn">spawns</a> a Bourne shell script
process. The full text of the <code>/bin/sh</code> shell script should be passed
in as the first argument. The <code>args</code> can be an array of arguments, not
including the executable, which are passed to the script as <code>$1</code>,
<code>$2</code> and so on. Shebang options are not used or respected.</p>
</div>
<div class="paragraph">
<p>The <code>options</code> is an optional javascript plain object and can include
any of the fields listed for the
<a href="#cockpit-spawn-spawn"><code>cockpit.spawn()</code></a> function.</p>
</div>
<div class="paragraph">
<p>The spawned process is a
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">promise</a>
that will complete if the script exits successfully, or fail if there&#8217;s
a problem. Some additional methods besides the standard promise methods
are documented below.</p>
</div>
<div class="paragraph">
<p>The standard output of the process is made available via the spawned
process object. Any non-UTF8 output from the process will be coerced
into textual form. It is highly recommended that only textual output be
produced by the command. The standard error is logged to the journal by
default.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-spawn-then">process.then()</h5>
<div class="literalblock">
<div class="content">
<pre>process.then((data[, message]) =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This is a standard
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">promise</a>
method. It sets up a handler to be called when the process finishes
successfully.</p>
</div>
<div class="paragraph">
<p>The <code>data</code> argument contains the standard output of the process. If it
a string, unless the process was opened in binary mode, in which case
the <code>data</code> is an array of bytes. If a <code>process.stream()</code> handler is
set up, then any standard output data consumed by the handler will not
be included in the <code>data</code> argument.</p>
</div>
<div class="paragraph">
<p>If the process was spawned with the <code>"err"</code> option set to
<code>"message"</code> then the second argument will contain the standard error
output of the process.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-spawn-catch">process.catch()</h5>
<div class="literalblock">
<div class="content">
<pre>process.catch((exception[, data]) =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This is a standard
<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise">Promise</a>
method. It sets up a handler to be called when the process fails,
terminates or exits.</p>
</div>
<div class="paragraph">
<p>The <code>exception</code> object passed to the handler can have the following
fields:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>message</code></dt>
<dd>
<p>A message describing the exception. If the process was spawned with
the <code>"err"</code> option set to <code>"message"</code> then the second argument
will contain the standard error output of the process.</p>
</dd>
<dt class="hdlist1"><code>problem</code></dt>
<dd>
<p>A <a href="#cockpit-problems">problem code</a> string when a problem occurred
starting or communicating with the process. This is <code>null</code> if the
process exited or was terminated.</p>
</dd>
<dt class="hdlist1"><code>exit_status</code></dt>
<dd>
<p>The numeric exit status of the process. This is <code>null</code> if the
process did not exit.</p>
</dd>
<dt class="hdlist1"><code>exit_signal</code></dt>
<dd>
<p>A string representing a unix signal that caused the process to
terminate. This is <code>null</code> if the process did not terminate because
of a signal.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>If the process actually ran and produced output before failing, it will
be available in the <code>data</code> argument. Otherwise this argument will be
<code>undefined</code>.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-spawn-stream">process.stream()</h5>
<div class="literalblock">
<div class="content">
<pre>process.stream(data =&gt; { ... })</pre>
</div>
</div>
<div class="paragraph">
<p>This sets up a handler to be called when the process has standard
output. The handler will be called multiple times. The handler will be
called regardless of whether the process ends up exiting successfully or
not.</p>
</div>
<div class="paragraph">
<p>Only one handler may be registered at a time. Registering an additional
handler replaces the previous one. The handler receives either string
<code>data</code> or an array of binary bytes as its argument. A stream handler
may return a number, which indicates the number of characters or bytes
consumed from <code>data</code>. Any data not consumed will be included again the
next time the handler is called.</p>
</div>
<div class="paragraph">
<p>If a <code>process.stream()</code> handler is set up, then the <code>process.then()</code>
handlers will only get any remaining data not consumed by the stream
handler.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-spawn-input">process.input()</h5>
<div class="literalblock">
<div class="content">
<pre>process.input(data, [stream])</pre>
</div>
</div>
<div class="paragraph">
<p>This method writes <code>data</code> to the standard input of the process. If
<code>data</code> is <code>null</code> or <code>undefined</code> it is not sent. The <code>data</code>
should be a string or an array of bytes if the process was opened in
binary mode.</p>
</div>
<div class="paragraph">
<p>If <code>stream</code> is set to <code>true</code> then this function may be called again
with further input. Otherwise the standard input of the process is
closed.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-spawn-close">process.close()</h5>
<div class="literalblock">
<div class="content">
<pre>process.close([problem])</pre>
</div>
</div>
<div class="paragraph">
<p>Close the process by closing its standard input and output. If
<code>problem</code> is specified it should be a standard
<a href="#cockpit-problems">problem code</a> string. In this case the process
will be terminated with a signal.</p>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_cockpit_js_utilities">cockpit.js: Utilities</h4>
<div class="paragraph">
<p>Various utility functions</p>
</div>
<div class="sect4">
<h5 id="cockpit-format">cockpit.format()</h5>
<div class="literalblock">
<div class="content">
<pre>string = cockpit.format(template, args)
string = cockpit.format(template, [arg, ...])</pre>
</div>
</div>
<div class="paragraph">
<p>Format a string interpolating <code>args</code> into <code>template</code> using shell
like syntax. The <code>args</code> may be either an array or javascript object.
The <code>template</code> can contain fields that look like <code>$name</code> or
<code>${name}</code> or <code>$0</code>. Numeric fields are used with array <code>args</code> and
start at zero.</p>
</div>
<div class="paragraph">
<p>In the second form, multiple <code>arg</code> arguments may be passed directly,
and interpolated as as numeric fields in the <code>template</code>.</p>
</div>
<div class="paragraph">
<p>All falsy arguments except the numbers <code>0</code> and `0.0`are replaced by
an empty string.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-format-number">cockpit.format_number()</h5>
<div class="literalblock">
<div class="content">
<pre>string = cockpit.format_number(number, [precision])</pre>
</div>
</div>
<div class="paragraph">
<p>Formats <code>number</code> into a displayable <code>string</code>. If the number is not
an integer, it is rounded to the given number of decimal places,
defaulting to 3. If the number is near zero, but not quite zero it is
rounded to the smallest non-zero value of the given precision; i.e.
±0.001 for default precision 3.</p>
</div>
<div class="paragraph">
<p>If <code>number</code> is <code>null</code> or <code>undefined</code> an empty string will be
returned.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-format-bytes">cockpit.format_bytes()</h5>
<div class="literalblock">
<div class="content">
<pre>string = cockpit.format_bytes(number, [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Formats <code>number</code> into a displayable <code>string</code> with a suffix, such as
<em>kB</em> or <em>MB</em>.</p>
</div>
<div class="paragraph">
<p>By default, SI units are used. IEC units (1024-based) can be requested
by including <code>base2: true</code> in <code>options</code>.</p>
</div>
<div class="paragraph">
<p>By default, non-integer numbers will be formatted with 3 digits of
precision. This can be changed with <code>options.precision</code>.</p>
</div>
<div class="paragraph">
<p>If <code>number</code> is <code>null</code> or <code>undefined</code> an empty string will be
returned.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-format-bytes-per-sec">cockpit.format_bytes_per_sec()</h5>
<div class="literalblock">
<div class="content">
<pre>string = cockpit.format_bytes_per_sec(number, [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Format <code>number</code> of bytes into a displayable speed <code>string</code>.</p>
</div>
<div class="paragraph">
<p>This function is mostly equivalent to <code>cockpit.format_bytes()</code> but the
returned value contains a unit like <em>kB/s</em> or <em>MB/s</em>.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-format-bits-per-sec">cockpit.format_bits_per_sec()</h5>
<div class="literalblock">
<div class="content">
<pre>string = cockpit.format_bits_per_sec(number, [options])</pre>
</div>
</div>
<div class="paragraph">
<p>Format <code>number</code> of bits into a displayable speed <code>string</code>.</p>
</div>
<div class="paragraph">
<p>This function is mostly equivalent to <code>cockpit.format_bytes()</code> but the
returned value contains a unit like <em>kbps</em> or <em>Mbps</em>.</p>
</div>
<div class="paragraph">
<p>This function does not support IEC units. <code>base2</code> may not be passed as
part of <code>options</code>.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-init">cockpit.init()</h5>
<div class="literalblock">
<div class="content">
<pre>await cockpit.init();

cockpit.init().then(() =&gt; { ... });</pre>
</div>
</div>
<div class="paragraph">
<p>Requests initialization of the Cockpit client library. This will ensure
that the transport is connected and we are ready to create channels. It
also populates the <code>cockpit.info</code> field.</p>
</div>
<div class="paragraph">
<p>This function returns a promise. Initialization isn&#8217;t complete until the
promise has resolved. You can either <code>await</code> it or call <code>.then()</code> on
it.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-info">cockpit.info</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.info.channels[payload]

cockpit.info.os_release[field]

cockpit.info.user

cockpit.info.ws.version</pre>
</div>
</div>
<div class="paragraph">
<p>This object contains information about Cockpit itself. It is only
available after cockpit.init() has been called and awaited.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>channels</code></dt>
<dd>
<p>This is a mapping of channel payload types (keys, strings) supported
by the bridge to capabilities advertised by those channels (values,
lists of strings). Channels are listed even if they don&#8217;t advertise
any capabilities, making this useful as a way to determine which
channel types are supported by the bridge.</p>
</dd>
<dt class="hdlist1"><code>os_release</code></dt>
<dd>
<p>This is the data from the <code>/etc/os-release</code> or
<code>/usr/lib/os-release</code> on the system that the bridge is running on.
It is a mapping from the key names to their values. See the
<a href="https://www.freedesktop.org/software/systemd/man/latest/os-release.html">os-release
Specification</a> for information about the available keys.</p>
</dd>
<dt class="hdlist1"><code>user</code></dt>
<dd>
<p>Contains information about the user we&#8217;re logged in as.</p>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>uid</code></dt>
<dd>
<p>This is unix user id as an integer.</p>
</dd>
<dt class="hdlist1"><code>gid</code></dt>
<dd>
<p>This is unix user group id as an integer.</p>
</dd>
<dt class="hdlist1"><code>name</code></dt>
<dd>
<p>This is the unix user name like <code>"root"</code>.</p>
</dd>
<dt class="hdlist1"><code>fullname</code></dt>
<dd>
<p>This is a readable name for the user, from the GECOS field.</p>
</dd>
<dt class="hdlist1"><code>group</code></dt>
<dd>
<p>This is the primary group name of the user.</p>
</dd>
<dt class="hdlist1"><code>groups</code></dt>
<dd>
<p>This is an array of group names to which the user belongs. The first
item in this list is the primary group.</p>
</dd>
<dt class="hdlist1"><code>home</code></dt>
<dd>
<p>This is user&#8217;s home directory.</p>
</dd>
<dt class="hdlist1"><code>shell</code></dt>
<dd>
<p>This is unix user shell.</p>
</dd>
</dl>
</div>
</dd>
<dt class="hdlist1"><code>ws</code></dt>
<dd>
<p>Contains information about the webserver Cockpit is being served with.</p>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>version</code></dt>
<dd>
<p>The version of the webserver.</p>
</dd>
</dl>
</div>
</dd>
</dl>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-event-target">cockpit.event_target</h5>
<div class="literalblock">
<div class="content">
<pre>cockpit.event_target(object, [handlers])</pre>
</div>
</div>
<div class="paragraph">
<p>Adds an
<a href="https://developer.mozilla.org/en-US/docs/Web/API/EventTarget">EventTarget</a>
implementation to the <code>object</code>. Optionally store the handlers in
<code>handlers</code> if its specified.</p>
</div>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_api_shell">API: shell</h3>
<div class="paragraph">
<p>This package contains the shell that loads other components.</p>
</div>
<div class="sect3">
<h4 id="_index_html">index.html</h4>
<div class="literalblock">
<div class="content">
<pre>&lt;iframe src="http://127.0.0.1:9090/cockpit+app/@localhost/shell/index.html"
    width="600" height="400"&gt;&lt;/iframe&gt;</pre>
</div>
</div>
<div class="paragraph">
<p>This is a Cockpit component that provides an interface to configure a
single machine. It loads other components on demand to make that happen.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Component URL</dt>
<dd>
<p><code>/cockpit+app/@localhost/shell/index.html</code></p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_api_system">API: system</h3>
<div class="paragraph">
<p>This package contains general components for basic control of a system.</p>
</div>
<div class="sect3">
<h4 id="_logs_html">logs.html</h4>
<div class="paragraph">
<p>System log component</p>
</div>
<div class="sect4">
<h5 id="api-logs-html-description">Description</h5>
<div class="literalblock">
<div class="content">
<pre>&lt;iframe src="http://127.0.0.1:9090/cockpit+app/@localhost/system/logs.html"
    width="600" height="400"&gt;&lt;/iframe&gt;</pre>
</div>
</div>
<div class="paragraph">
<p>This is a Cockpit component that brings up system log viewer, with
filtering capabilities. On systemd based systems this displays the
entries from journal.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Component URL</dt>
<dd>
<p><code>/cockpit+app/@localhost/system/logs.html</code></p>
</dd>
<dt class="hdlist1">Filter by priority</dt>
<dd>
<p><code>#?prio=notice</code><br>
<br>
Filters the log to show entries below the specific priority,
inclusive. These
<a href="https://en.wikipedia.org/wiki/Syslog#Severity_levels">priorities are
syslog level keywords</a>. Specifying <code>*</code> as a priority will show all
available entries. The default priority is <code>err</code>.</p>
</dd>
<dt class="hdlist1">Filter by service</dt>
<dd>
<p><code>#?service=sshd.service</code><br>
<br>
Filters the log to show entries related to the specific service. The
format of the service is specific to the logging implementation. For
journald these are systemd service unit names.</p>
</dd>
<dt class="hdlist1">Filter by tag</dt>
<dd>
<p><code>#?tag=kernel</code><br>
<br>
Filters the log to show entries related to the specific syslog
identifier.</p>
</dd>
<dt class="hdlist1">Filter by message</dt>
<dd>
<p><code>#?grep=</code><br>
<br>
Filters the log to show entries where the <code>MESSAGE=</code> field matches
the specified regular expression. PERL-compatible regular expressions
are used. If the pattern is all lowercase, matching is case
insensitive. Otherwise, matching is case sensitive.</p>
</dd>
<dt class="hdlist1">Filter by any field</dt>
<dd>
<p><code>#?FIELD=VALUE</code><br>
<br>
A field is referring to the components of a structured journal entry.
The match must be exact. Value can be comma separated list in which
case they are automatically matched as alternatives.</p>
</dd>
<dt class="hdlist1">Start at point</dt>
<dd>
<p><code>#?start=boot</code><br>
<br>
Filters the log to show entries after the specific point in time.
Valid values are <code>boot</code> (since last boot), <code>last-24h</code> (last 24
hours), <code>last-week</code> (last seven days) and <code>previous-boot</code>
(previous boot).</p>
</dd>
<dt class="hdlist1">Follow the journal</dt>
<dd>
<p><code>#?follow=true</code><br>
<br>
Keep listening on new entries. Valid values are <code>true</code> (follow) and
<code>false</code> (do not follow).</p>
</dd>
<dt class="hdlist1">Show log entry</dt>
<dd>
<p><code>#/6e272d82993c4e0d...</code><br>
<br>
To show a specific log entry, put the log entry cursor in a path after
the hash above. Note that cursors are logging system specific, and
journal cursors are subject to change.</p>
</dd>
</dl>
</div>
</div>
</div>
<div class="sect3">
<h4 id="_terminal_html">terminal.html</h4>
<div class="paragraph">
<p>Server terminal component</p>
</div>
<div class="sect4">
<h5 id="api-terminal-html-description">Description</h5>
<div class="literalblock">
<div class="content">
<pre>&lt;iframe src="http://127.0.0.1:9090/cockpit+app/@localhost/system/terminal.html"
    width="600" height="400"&gt;&lt;/iframe&gt;</pre>
</div>
</div>
<div class="paragraph">
<p>This is a Cockpit component that brings up a web-based terminal for the
logged in user.</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Component URL</dt>
<dd>
<p><code>/cockpit+app/@localhost/system/terminal.html</code></p>
</dd>
</dl>
</div>
</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>