File: development.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 (5402 lines) | stat: -rw-r--r-- 209,916 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>Developer Guide</title>
<style>
/*! Asciidoctor default stylesheet | MIT License | https://asciidoctor.org */
/* Uncomment the following line when using as a custom stylesheet */
/* @import "https://fonts.googleapis.com/css?family=Open+Sans:300,300italic,400,400italic,600,600italic%7CNoto+Serif:400,400italic,700,700italic%7CDroid+Sans+Mono:400,700"; */
html{font-family:sans-serif;-webkit-text-size-adjust:100%}
a{background:none}
a:focus{outline:thin dotted}
a:active,a:hover{outline:0}
h1{font-size:2em;margin:.67em 0}
b,strong{font-weight:bold}
abbr{font-size:.9em}
abbr[title]{cursor:help;border-bottom:1px dotted #dddddf;text-decoration:none}
dfn{font-style:italic}
hr{height:0}
mark{background:#ff0;color:#000}
code,kbd,pre,samp{font-family:monospace;font-size:1em}
pre{white-space:pre-wrap}
q{quotes:"\201C" "\201D" "\2018" "\2019"}
small{font-size:80%}
sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}
sup{top:-.5em}
sub{bottom:-.25em}
img{border:0}
svg:not(:root){overflow:hidden}
figure{margin:0}
audio,video{display:inline-block}
audio:not([controls]){display:none;height:0}
fieldset{border:1px solid silver;margin:0 2px;padding:.35em .625em .75em}
legend{border:0;padding:0}
button,input,select,textarea{font-family:inherit;font-size:100%;margin:0}
button,input{line-height:normal}
button,select{text-transform:none}
button,html input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer}
button[disabled],html input[disabled]{cursor:default}
input[type=checkbox],input[type=radio]{padding:0}
button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}
textarea{overflow:auto;vertical-align:top}
table{border-collapse:collapse;border-spacing:0}
*,::before,::after{box-sizing:border-box}
html,body{font-size:100%}
body{background:#fff;color:rgba(0,0,0,.8);padding:0;margin:0;font-family:"Noto Serif","DejaVu Serif",serif;line-height:1;position:relative;cursor:auto;-moz-tab-size:4;-o-tab-size:4;tab-size:4;word-wrap:anywhere;-moz-osx-font-smoothing:grayscale;-webkit-font-smoothing:antialiased}
a:hover{cursor:pointer}
img,object,embed{max-width:100%;height:auto}
object,embed{height:100%}
img{-ms-interpolation-mode:bicubic}
.left{float:left!important}
.right{float:right!important}
.text-left{text-align:left!important}
.text-right{text-align:right!important}
.text-center{text-align:center!important}
.text-justify{text-align:justify!important}
.hide{display:none}
img,object,svg{display:inline-block;vertical-align:middle}
textarea{height:auto;min-height:50px}
select{width:100%}
.subheader,.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{line-height:1.45;color:#7a2518;font-weight:400;margin-top:0;margin-bottom:.25em}
div,dl,dt,dd,ul,ol,li,h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6,pre,form,p,blockquote,th,td{margin:0;padding:0}
a{color:#2156a5;text-decoration:underline;line-height:inherit}
a:hover,a:focus{color:#1d4b8f}
a img{border:0}
p{line-height:1.6;margin-bottom:1.25em;text-rendering:optimizeLegibility}
p aside{font-size:.875em;line-height:1.35;font-style:italic}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{font-family:"Open Sans","DejaVu Sans",sans-serif;font-weight:300;font-style:normal;color:#ba3925;text-rendering:optimizeLegibility;margin-top:1em;margin-bottom:.5em;line-height:1.0125em}
h1 small,h2 small,h3 small,#toctitle small,.sidebarblock>.content>.title small,h4 small,h5 small,h6 small{font-size:60%;color:#e99b8f;line-height:0}
h1{font-size:2.125em}
h2{font-size:1.6875em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.375em}
h4,h5{font-size:1.125em}
h6{font-size:1em}
hr{border:solid #dddddf;border-width:1px 0 0;clear:both;margin:1.25em 0 1.1875em}
em,i{font-style:italic;line-height:inherit}
strong,b{font-weight:bold;line-height:inherit}
small{font-size:60%;line-height:inherit}
code{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;font-weight:400;color:rgba(0,0,0,.9)}
ul,ol,dl{line-height:1.6;margin-bottom:1.25em;list-style-position:outside;font-family:inherit}
ul,ol{margin-left:1.5em}
ul li ul,ul li ol{margin-left:1.25em;margin-bottom:0}
ul.circle{list-style-type:circle}
ul.disc{list-style-type:disc}
ul.square{list-style-type:square}
ul.circle ul:not([class]),ul.disc ul:not([class]),ul.square ul:not([class]){list-style:inherit}
ol li ul,ol li ol{margin-left:1.25em;margin-bottom:0}
dl dt{margin-bottom:.3125em;font-weight:bold}
dl dd{margin-bottom:1.25em}
blockquote{margin:0 0 1.25em;padding:.5625em 1.25em 0 1.1875em;border-left:1px solid #ddd}
blockquote,blockquote p{line-height:1.6;color:rgba(0,0,0,.85)}
@media screen and (min-width:768px){h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2}
h1{font-size:2.75em}
h2{font-size:2.3125em}
h3,#toctitle,.sidebarblock>.content>.title{font-size:1.6875em}
h4{font-size:1.4375em}}
table{background:#fff;margin-bottom:1.25em;border:1px solid #dedede;word-wrap:normal}
table thead,table tfoot{background:#f7f8f7}
table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;color:rgba(0,0,0,.8);text-align:left}
table tr th,table tr td{padding:.5625em .625em;font-size:inherit;color:rgba(0,0,0,.8)}
table tr.even,table tr.alt{background:#f8f8f7}
table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{line-height:1.6}
h1,h2,h3,#toctitle,.sidebarblock>.content>.title,h4,h5,h6{line-height:1.2;word-spacing:-.05em}
h1 strong,h2 strong,h3 strong,#toctitle strong,.sidebarblock>.content>.title strong,h4 strong,h5 strong,h6 strong{font-weight:400}
.center{margin-left:auto;margin-right:auto}
.stretch{width:100%}
.clearfix::before,.clearfix::after,.float-group::before,.float-group::after{content:" ";display:table}
.clearfix::after,.float-group::after{clear:both}
:not(pre).nobreak{word-wrap:normal}
:not(pre).nowrap{white-space:nowrap}
:not(pre).pre-wrap{white-space:pre-wrap}
:not(pre):not([class^=L])>code{font-size:.9375em;font-style:normal!important;letter-spacing:0;padding:.1em .5ex;word-spacing:-.15em;background:#f7f7f8;border-radius:4px;line-height:1.45;text-rendering:optimizeSpeed}
pre{color:rgba(0,0,0,.9);font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;line-height:1.45;text-rendering:optimizeSpeed}
pre code,pre pre{color:inherit;font-size:inherit;line-height:inherit}
pre.nowrap,pre.nowrap pre{white-space:pre;word-wrap:normal}
em em{font-style:normal}
strong strong{font-weight:400}
.keyseq{color:rgba(51,51,51,.8)}
kbd{font-family:"Droid Sans Mono","DejaVu Sans Mono",monospace;display:inline-block;color:rgba(0,0,0,.8);font-size:.65em;line-height:1.45;background:#f7f7f7;border:1px solid #ccc;border-radius:3px;box-shadow:0 1px 0 rgba(0,0,0,.2),inset 0 0 0 .1em #fff;margin:0 .15em;padding:.2em .5em;vertical-align:middle;position:relative;top:-.1em;white-space:nowrap}
.keyseq kbd:first-child{margin-left:0}
.keyseq kbd:last-child{margin-right:0}
.menuseq,.menuref{color:#000}
.menuseq b:not(.caret),.menuref{font-weight:inherit}
.menuseq{word-spacing:-.02em}
.menuseq b.caret{font-size:1.25em;line-height:.8}
.menuseq i.caret{font-weight:bold;text-align:center;width:.45em}
b.button::before,b.button::after{position:relative;top:-1px;font-weight:400}
b.button::before{content:"[";padding:0 3px 0 2px}
b.button::after{content:"]";padding:0 2px 0 3px}
p a>code:hover{color:rgba(0,0,0,.9)}
#header,#content,#footnotes,#footer{width:100%;margin:0 auto;max-width:62.5em;*zoom:1;position:relative;padding-left:.9375em;padding-right:.9375em}
#header::before,#header::after,#content::before,#content::after,#footnotes::before,#footnotes::after,#footer::before,#footer::after{content:" ";display:table}
#header::after,#content::after,#footnotes::after,#footer::after{clear:both}
#content{margin-top:1.25em}
#content::before{content:none}
#header>h1:first-child{color:rgba(0,0,0,.85);margin-top:2.25rem;margin-bottom:0}
#header>h1:first-child+#toc{margin-top:8px;border-top:1px solid #dddddf}
#header>h1:only-child{border-bottom:1px solid #dddddf;padding-bottom:8px}
#header .details{border-bottom:1px solid #dddddf;line-height:1.45;padding-top:.25em;padding-bottom:.25em;padding-left:.25em;color:rgba(0,0,0,.6);display:flex;flex-flow:row wrap}
#header .details span:first-child{margin-left:-.125em}
#header .details span.email a{color:rgba(0,0,0,.85)}
#header .details br{display:none}
#header .details br+span::before{content:"\00a0\2013\00a0"}
#header .details br+span.author::before{content:"\00a0\22c5\00a0";color:rgba(0,0,0,.85)}
#header .details br+span#revremark::before{content:"\00a0|\00a0"}
#header #revnumber{text-transform:capitalize}
#header #revnumber::after{content:"\00a0"}
#content>h1:first-child:not([class]){color:rgba(0,0,0,.85);border-bottom:1px solid #dddddf;padding-bottom:8px;margin-top:0;padding-top:1rem;margin-bottom:1.25rem}
#toc{border-bottom:1px solid #e7e7e9;padding-bottom:.5em}
#toc>ul{margin-left:.125em}
#toc ul.sectlevel0>li>a{font-style:italic}
#toc ul.sectlevel0 ul.sectlevel1{margin:.5em 0}
#toc ul{font-family:"Open Sans","DejaVu Sans",sans-serif;list-style-type:none}
#toc li{line-height:1.3334;margin-top:.3334em}
#toc a{text-decoration:none}
#toc a:active{text-decoration:underline}
#toctitle{color:#7a2518;font-size:1.2em}
@media screen and (min-width:768px){#toctitle{font-size:1.375em}
body.toc2{padding-left:15em;padding-right:0}
body.toc2 #header>h1:nth-last-child(2){border-bottom:1px solid #dddddf;padding-bottom:8px}
#toc.toc2{margin-top:0!important;background:#f8f8f7;position:fixed;width:15em;left:0;top:0;border-right:1px solid #e7e7e9;border-top-width:0!important;border-bottom-width:0!important;z-index:1000;padding:1.25em 1em;height:100%;overflow:auto}
#toc.toc2 #toctitle{margin-top:0;margin-bottom:.8rem;font-size:1.2em}
#toc.toc2>ul{font-size:.9em;margin-bottom:0}
#toc.toc2 ul ul{margin-left:0;padding-left:1em}
#toc.toc2 ul.sectlevel0 ul.sectlevel1{padding-left:0;margin-top:.5em;margin-bottom:.5em}
body.toc2.toc-right{padding-left:0;padding-right:15em}
body.toc2.toc-right #toc.toc2{border-right-width:0;border-left:1px solid #e7e7e9;left:auto;right:0}}
@media screen and (min-width:1280px){body.toc2{padding-left:20em;padding-right:0}
#toc.toc2{width:20em}
#toc.toc2 #toctitle{font-size:1.375em}
#toc.toc2>ul{font-size:.95em}
#toc.toc2 ul ul{padding-left:1.25em}
body.toc2.toc-right{padding-left:0;padding-right:20em}}
#content #toc{border:1px solid #e0e0dc;margin-bottom:1.25em;padding:1.25em;background:#f8f8f7;border-radius:4px}
#content #toc>:first-child{margin-top:0}
#content #toc>:last-child{margin-bottom:0}
#footer{max-width:none;background:rgba(0,0,0,.8);padding:1.25em}
#footer-text{color:hsla(0,0%,100%,.8);line-height:1.44}
#content{margin-bottom:.625em}
.sect1{padding-bottom:.625em}
@media screen and (min-width:768px){#content{margin-bottom:1.25em}
.sect1{padding-bottom:1.25em}}
.sect1:last-child{padding-bottom:0}
.sect1+.sect1{border-top:1px solid #e7e7e9}
#content h1>a.anchor,h2>a.anchor,h3>a.anchor,#toctitle>a.anchor,.sidebarblock>.content>.title>a.anchor,h4>a.anchor,h5>a.anchor,h6>a.anchor{position:absolute;z-index:1001;width:1.5ex;margin-left:-1.5ex;display:block;text-decoration:none!important;visibility:hidden;text-align:center;font-weight:400}
#content h1>a.anchor::before,h2>a.anchor::before,h3>a.anchor::before,#toctitle>a.anchor::before,.sidebarblock>.content>.title>a.anchor::before,h4>a.anchor::before,h5>a.anchor::before,h6>a.anchor::before{content:"\00A7";font-size:.85em;display:block;padding-top:.1em}
#content h1:hover>a.anchor,#content h1>a.anchor:hover,h2:hover>a.anchor,h2>a.anchor:hover,h3:hover>a.anchor,#toctitle:hover>a.anchor,.sidebarblock>.content>.title:hover>a.anchor,h3>a.anchor:hover,#toctitle>a.anchor:hover,.sidebarblock>.content>.title>a.anchor:hover,h4:hover>a.anchor,h4>a.anchor:hover,h5:hover>a.anchor,h5>a.anchor:hover,h6:hover>a.anchor,h6>a.anchor:hover{visibility:visible}
#content h1>a.link,h2>a.link,h3>a.link,#toctitle>a.link,.sidebarblock>.content>.title>a.link,h4>a.link,h5>a.link,h6>a.link{color:#ba3925;text-decoration:none}
#content h1>a.link:hover,h2>a.link:hover,h3>a.link:hover,#toctitle>a.link:hover,.sidebarblock>.content>.title>a.link:hover,h4>a.link:hover,h5>a.link:hover,h6>a.link:hover{color:#a53221}
details,.audioblock,.imageblock,.literalblock,.listingblock,.stemblock,.videoblock{margin-bottom:1.25em}
details{margin-left:1.25rem}
details>summary{cursor:pointer;display:block;position:relative;line-height:1.6;margin-bottom:.625rem;outline:none;-webkit-tap-highlight-color:transparent}
details>summary::-webkit-details-marker{display:none}
details>summary::before{content:"";border:solid transparent;border-left:solid;border-width:.3em 0 .3em .5em;position:absolute;top:.5em;left:-1.25rem;transform:translateX(15%)}
details[open]>summary::before{border:solid transparent;border-top:solid;border-width:.5em .3em 0;transform:translateY(15%)}
details>summary::after{content:"";width:1.25rem;height:1em;position:absolute;top:.3em;left:-1.25rem}
.admonitionblock td.content>.title,.audioblock>.title,.exampleblock>.title,.imageblock>.title,.listingblock>.title,.literalblock>.title,.stemblock>.title,.openblock>.title,.paragraph>.title,.quoteblock>.title,table.tableblock>.title,.verseblock>.title,.videoblock>.title,.dlist>.title,.olist>.title,.ulist>.title,.qlist>.title,.hdlist>.title{text-rendering:optimizeLegibility;text-align:left;font-family:"Noto Serif","DejaVu Serif",serif;font-size:1rem;font-style:italic}
table.tableblock.fit-content>caption.title{white-space:nowrap;width:0}
.paragraph.lead>p,#preamble>.sectionbody>[class=paragraph]:first-of-type p{font-size:1.21875em;line-height:1.6;color:rgba(0,0,0,.85)}
.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%}
.admonitionblock>table td.icon{text-align:center;width:80px}
.admonitionblock>table td.icon img{max-width:none}
.admonitionblock>table td.icon .title{font-weight:bold;font-family:"Open Sans","DejaVu Sans",sans-serif;text-transform:uppercase}
.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #dddddf;color:rgba(0,0,0,.6);word-wrap:anywhere}
.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0}
.exampleblock>.content{border:1px solid #e6e6e6;margin-bottom:1.25em;padding:1.25em;background:#fff;border-radius:4px}
.sidebarblock{border:1px solid #dbdbd6;margin-bottom:1.25em;padding:1.25em;background:#f3f3f2;border-radius:4px}
.sidebarblock>.content>.title{color:#7a2518;margin-top:0;text-align:center}
.exampleblock>.content>:first-child,.sidebarblock>.content>:first-child{margin-top:0}
.exampleblock>.content>:last-child,.exampleblock>.content>:last-child>:last-child,.exampleblock>.content .olist>ol>li:last-child>:last-child,.exampleblock>.content .ulist>ul>li:last-child>:last-child,.exampleblock>.content .qlist>ol>li:last-child>:last-child,.sidebarblock>.content>:last-child,.sidebarblock>.content>:last-child>:last-child,.sidebarblock>.content .olist>ol>li:last-child>:last-child,.sidebarblock>.content .ulist>ul>li:last-child>:last-child,.sidebarblock>.content .qlist>ol>li:last-child>:last-child{margin-bottom:0}
.literalblock pre,.listingblock>.content>pre{border-radius:4px;overflow-x:auto;padding:1em;font-size:.8125em}
@media screen and (min-width:768px){.literalblock pre,.listingblock>.content>pre{font-size:.90625em}}
@media screen and (min-width:1280px){.literalblock pre,.listingblock>.content>pre{font-size:1em}}
.literalblock pre,.listingblock>.content>pre:not(.highlight),.listingblock>.content>pre[class=highlight],.listingblock>.content>pre[class^="highlight "]{background:#f7f7f8}
.literalblock.output pre{color:#f7f7f8;background:rgba(0,0,0,.9)}
.listingblock>.content{position:relative}
.listingblock pre>code{display:block}
.listingblock code[data-lang]::before{display:none;content:attr(data-lang);position:absolute;font-size:.75em;top:.425rem;right:.5rem;line-height:1;text-transform:uppercase;color:inherit;opacity:.5}
.listingblock:hover code[data-lang]::before{display:block}
.listingblock.terminal pre .command::before{content:attr(data-prompt);padding-right:.5em;color:inherit;opacity:.5}
.listingblock.terminal pre .command:not([data-prompt])::before{content:"$"}
.listingblock pre.highlightjs{padding:0}
.listingblock pre.highlightjs>code{padding:1em;border-radius:4px}
.listingblock pre.prettyprint{border-width:0}
.prettyprint{background:#f7f7f8}
pre.prettyprint .linenums{line-height:1.45;margin-left:2em}
pre.prettyprint li{background:none;list-style-type:inherit;padding-left:0}
pre.prettyprint li code[data-lang]::before{opacity:1}
pre.prettyprint li:not(:first-child) code[data-lang]::before{display:none}
table.linenotable{border-collapse:separate;border:0;margin-bottom:0;background:none}
table.linenotable td[class]{color:inherit;vertical-align:top;padding:0;line-height:inherit;white-space:normal}
table.linenotable td.code{padding-left:.75em}
table.linenotable td.linenos,pre.pygments .linenos{border-right:1px solid;opacity:.35;padding-right:.5em;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
pre.pygments span.linenos{display:inline-block;margin-right:.75em}
.quoteblock{margin:0 1em 1.25em 1.5em;display:table}
.quoteblock:not(.excerpt)>.title{margin-left:-1.5em;margin-bottom:.75em}
.quoteblock blockquote,.quoteblock p{color:rgba(0,0,0,.85);font-size:1.15rem;line-height:1.75;word-spacing:.1em;letter-spacing:0;font-style:italic;text-align:justify}
.quoteblock blockquote{margin:0;padding:0;border:0}
.quoteblock blockquote::before{content:"\201c";float:left;font-size:2.75em;font-weight:bold;line-height:.6em;margin-left:-.6em;color:#7a2518;text-shadow:0 1px 2px rgba(0,0,0,.1)}
.quoteblock blockquote>.paragraph:last-child p{margin-bottom:0}
.quoteblock .attribution{margin-top:.75em;margin-right:.5ex;text-align:right}
.verseblock{margin:0 1em 1.25em}
.verseblock pre{font-family:"Open Sans","DejaVu Sans",sans-serif;font-size:1.15rem;color:rgba(0,0,0,.85);font-weight:300;text-rendering:optimizeLegibility}
.verseblock pre strong{font-weight:400}
.verseblock .attribution{margin-top:1.25rem;margin-left:.5ex}
.quoteblock .attribution,.verseblock .attribution{font-size:.9375em;line-height:1.45;font-style:italic}
.quoteblock .attribution br,.verseblock .attribution br{display:none}
.quoteblock .attribution cite,.verseblock .attribution cite{display:block;letter-spacing:-.025em;color:rgba(0,0,0,.6)}
.quoteblock.abstract blockquote::before,.quoteblock.excerpt blockquote::before,.quoteblock .quoteblock blockquote::before{display:none}
.quoteblock.abstract blockquote,.quoteblock.abstract p,.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{line-height:1.6;word-spacing:0}
.quoteblock.abstract{margin:0 1em 1.25em;display:block}
.quoteblock.abstract>.title{margin:0 0 .375em;font-size:1.15em;text-align:center}
.quoteblock.excerpt>blockquote,.quoteblock .quoteblock{padding:0 0 .25em 1em;border-left:.25em solid #dddddf}
.quoteblock.excerpt,.quoteblock .quoteblock{margin-left:0}
.quoteblock.excerpt blockquote,.quoteblock.excerpt p,.quoteblock .quoteblock blockquote,.quoteblock .quoteblock p{color:inherit;font-size:1.0625rem}
.quoteblock.excerpt .attribution,.quoteblock .quoteblock .attribution{color:inherit;font-size:.85rem;text-align:left;margin-right:0}
p.tableblock:last-child{margin-bottom:0}
td.tableblock>.content{margin-bottom:1.25em;word-wrap:anywhere}
td.tableblock>.content>:last-child{margin-bottom:-1.25em}
table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
table.grid-all>*>tr>*{border-width:1px}
table.grid-cols>*>tr>*{border-width:0 1px}
table.grid-rows>*>tr>*{border-width:1px 0}
table.frame-all{border-width:1px}
table.frame-ends{border-width:1px 0}
table.frame-sides{border-width:0 1px}
table.frame-none>colgroup+*>:first-child>*,table.frame-sides>colgroup+*>:first-child>*{border-top-width:0}
table.frame-none>:last-child>:last-child>*,table.frame-sides>:last-child>:last-child>*{border-bottom-width:0}
table.frame-none>*>tr>:first-child,table.frame-ends>*>tr>:first-child{border-left-width:0}
table.frame-none>*>tr>:last-child,table.frame-ends>*>tr>:last-child{border-right-width:0}
table.stripes-all>*>tr,table.stripes-odd>*>tr:nth-of-type(odd),table.stripes-even>*>tr:nth-of-type(even),table.stripes-hover>*>tr:hover{background:#f8f8f7}
th.halign-left,td.halign-left{text-align:left}
th.halign-right,td.halign-right{text-align:right}
th.halign-center,td.halign-center{text-align:center}
th.valign-top,td.valign-top{vertical-align:top}
th.valign-bottom,td.valign-bottom{vertical-align:bottom}
th.valign-middle,td.valign-middle{vertical-align:middle}
table thead th,table tfoot th{font-weight:bold}
tbody tr th{background:#f7f8f7}
tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{color:rgba(0,0,0,.8);font-weight:bold}
p.tableblock>code:only-child{background:none;padding:0}
p.tableblock{font-size:1em}
ol{margin-left:1.75em}
ul li ol{margin-left:1.5em}
dl dd{margin-left:1.125em}
dl dd:last-child,dl dd:last-child>:last-child{margin-bottom:0}
li p,ul dd,ol dd,.olist .olist,.ulist .ulist,.ulist .olist,.olist .ulist{margin-bottom:.625em}
ul.checklist,ul.none,ol.none,ul.no-bullet,ol.no-bullet,ol.unnumbered,ul.unstyled,ol.unstyled{list-style-type:none}
ul.no-bullet,ol.no-bullet,ol.unnumbered{margin-left:.625em}
ul.unstyled,ol.unstyled{margin-left:0}
li>p:empty:only-child::before{content:"";display:inline-block}
ul.checklist>li>p:first-child{margin-left:-1em}
ul.checklist>li>p:first-child>.fa-square-o:first-child,ul.checklist>li>p:first-child>.fa-check-square-o:first-child{width:1.25em;font-size:.8em;position:relative;bottom:.125em}
ul.checklist>li>p:first-child>input[type=checkbox]:first-child{margin-right:.25em}
ul.inline{display:flex;flex-flow:row wrap;list-style:none;margin:0 0 .625em -1.25em}
ul.inline>li{margin-left:1.25em}
.unstyled dl dt{font-weight:400;font-style:normal}
ol.arabic{list-style-type:decimal}
ol.decimal{list-style-type:decimal-leading-zero}
ol.loweralpha{list-style-type:lower-alpha}
ol.upperalpha{list-style-type:upper-alpha}
ol.lowerroman{list-style-type:lower-roman}
ol.upperroman{list-style-type:upper-roman}
ol.lowergreek{list-style-type:lower-greek}
.hdlist>table,.colist>table{border:0;background:none}
.hdlist>table>tbody>tr,.colist>table>tbody>tr{background:none}
td.hdlist1,td.hdlist2{vertical-align:top;padding:0 .625em}
td.hdlist1{font-weight:bold;padding-bottom:1.25em}
td.hdlist2{word-wrap:anywhere}
.literalblock+.colist,.listingblock+.colist{margin-top:-.5em}
.colist td:not([class]):first-child{padding:.4em .75em 0;line-height:1;vertical-align:top}
.colist td:not([class]):first-child img{max-width:none}
.colist td:not([class]):last-child{padding:.25em 0}
.thumb,.th{line-height:0;display:inline-block;border:4px solid #fff;box-shadow:0 0 0 1px #ddd}
.imageblock.left{margin:.25em .625em 1.25em 0}
.imageblock.right{margin:.25em 0 1.25em .625em}
.imageblock>.title{margin-bottom:0}
.imageblock.thumb,.imageblock.th{border-width:6px}
.imageblock.thumb>.title,.imageblock.th>.title{padding:0 .125em}
.image.left,.image.right{margin-top:.25em;margin-bottom:.25em;display:inline-block;line-height:0}
.image.left{margin-right:.625em}
.image.right{margin-left:.625em}
a.image{text-decoration:none;display:inline-block}
a.image object{pointer-events:none}
sup.footnote,sup.footnoteref{font-size:.875em;position:static;vertical-align:super}
sup.footnote a,sup.footnoteref a{text-decoration:none}
sup.footnote a:active,sup.footnoteref a:active,#footnotes .footnote a:first-of-type:active{text-decoration:underline}
#footnotes{padding-top:.75em;padding-bottom:.75em;margin-bottom:.625em}
#footnotes hr{width:20%;min-width:6.25em;margin:-.25em 0 .75em;border-width:1px 0 0}
#footnotes .footnote{padding:0 .375em 0 .225em;line-height:1.3334;font-size:.875em;margin-left:1.2em;margin-bottom:.2em}
#footnotes .footnote a:first-of-type{font-weight:bold;text-decoration:none;margin-left:-1.05em}
#footnotes .footnote:last-of-type{margin-bottom:0}
#content #footnotes{margin-top:-.625em;margin-bottom:0;padding:.75em 0}
div.unbreakable{page-break-inside:avoid}
.big{font-size:larger}
.small{font-size:smaller}
.underline{text-decoration:underline}
.overline{text-decoration:overline}
.line-through{text-decoration:line-through}
.aqua{color:#00bfbf}
.aqua-background{background:#00fafa}
.black{color:#000}
.black-background{background:#000}
.blue{color:#0000bf}
.blue-background{background:#0000fa}
.fuchsia{color:#bf00bf}
.fuchsia-background{background:#fa00fa}
.gray{color:#606060}
.gray-background{background:#7d7d7d}
.green{color:#006000}
.green-background{background:#007d00}
.lime{color:#00bf00}
.lime-background{background:#00fa00}
.maroon{color:#600000}
.maroon-background{background:#7d0000}
.navy{color:#000060}
.navy-background{background:#00007d}
.olive{color:#606000}
.olive-background{background:#7d7d00}
.purple{color:#600060}
.purple-background{background:#7d007d}
.red{color:#bf0000}
.red-background{background:#fa0000}
.silver{color:#909090}
.silver-background{background:#bcbcbc}
.teal{color:#006060}
.teal-background{background:#007d7d}
.white{color:#bfbfbf}
.white-background{background:#fafafa}
.yellow{color:#bfbf00}
.yellow-background{background:#fafa00}
span.icon>.fa{cursor:default}
a span.icon>.fa{cursor:inherit}
.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default}
.admonitionblock td.icon .icon-note::before{content:"\f05a";color:#19407c}
.admonitionblock td.icon .icon-tip::before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111}
.admonitionblock td.icon .icon-warning::before{content:"\f071";color:#bf6900}
.admonitionblock td.icon .icon-caution::before{content:"\f06d";color:#bf3400}
.admonitionblock td.icon .icon-important::before{content:"\f06a";color:#bf0000}
.conum[data-value]{display:inline-block;color:#fff!important;background:rgba(0,0,0,.8);border-radius:50%;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
.conum[data-value] *{color:#fff!important}
.conum[data-value]+b{display:none}
.conum[data-value]::after{content:attr(data-value)}
pre .conum[data-value]{position:relative;top:-.125em}
b.conum *{color:inherit!important}
.conum:not([data-value]):empty{display:none}
dt,th.tableblock,td.content,div.footnote{text-rendering:optimizeLegibility}
h1,h2,p,td.content,span.alt,summary{letter-spacing:-.01em}
p strong,td.content strong,div.footnote strong{letter-spacing:-.005em}
p,blockquote,dt,td.content,td.hdlist1,span.alt,summary{font-size:1.0625rem}
p{margin-bottom:1.25rem}
.sidebarblock p,.sidebarblock dt,.sidebarblock td.content,p.tableblock{font-size:1em}
.exampleblock>.content{background:#fffef7;border-color:#e0e0dc;box-shadow:0 1px 4px #e0e0dc}
.print-only{display:none!important}
@page{margin:1.25cm .75cm}
@media print{*{box-shadow:none!important;text-shadow:none!important}
html{font-size:80%}
a{color:inherit!important;text-decoration:underline!important}
a.bare,a[href^="#"],a[href^="mailto:"]{text-decoration:none!important}
a[href^="http:"]:not(.bare)::after,a[href^="https:"]:not(.bare)::after{content:"(" attr(href) ")";display:inline-block;font-size:.875em;padding-left:.25em}
abbr[title]{border-bottom:1px dotted}
abbr[title]::after{content:" (" attr(title) ")"}
pre,blockquote,tr,img,object,svg{page-break-inside:avoid}
thead{display:table-header-group}
svg{max-width:100%}
p,blockquote,dt,td.content{font-size:1em;orphans:3;widows:3}
h2,h3,#toctitle,.sidebarblock>.content>.title{page-break-after:avoid}
#header,#content,#footnotes,#footer{max-width:none}
#toc,.sidebarblock,.exampleblock>.content{background:none!important}
#toc{border-bottom:1px solid #dddddf!important;padding-bottom:0!important}
body.book #header{text-align:center}
body.book #header>h1:first-child{border:0!important;margin:2.5em 0 1em}
body.book #header .details{border:0!important;display:block;padding:0!important}
body.book #header .details span:first-child{margin-left:0!important}
body.book #header .details br{display:block}
body.book #header .details br+span::before{content:none!important}
body.book #toc{border:0!important;text-align:left!important;padding:0!important;margin:0!important}
body.book #toc,body.book #preamble,body.book h1.sect0,body.book .sect1>h2{page-break-before:always}
.listingblock code[data-lang]::before{display:block}
#footer{padding:0 .9375em}
.hide-on-print{display:none!important}
.print-only{display:block!important}
.hide-for-print{display:none!important}
.show-for-print{display:inherit!important}}
@media amzn-kf8,print{#header>h1:first-child{margin-top:1.25rem}
.sect1{padding:0!important}
.sect1+.sect1{border:0}
#footer{background:none}
#footer-text{color:rgba(0,0,0,.6);font-size:.9em}}
@media amzn-kf8{#header,#content,#footnotes,#footer{padding:0}}
</style>
</head>
<body id="development" class="article toc2 toc-left">
<div id="header">
<h1>Developer Guide</h1>
<div id="toc" class="toc2">
<div id="toctitle">Table of Contents</div>
<ul class="sectlevel1">
<li><a href="#embedding">Embedding and Integrating Cockpit</a>
<ul class="sectlevel2">
<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="sectlevel2">
<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="sectlevel2">
<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="sectlevel2">
<li><a href="#_cockpit_js">cockpit.js</a>
<ul class="sectlevel3">
<li><a href="#api-cockpit-loading">Loading cockpit.js</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_object_caching">cockpit.js: Object Caching</a>
<ul class="sectlevel3">
<li><a href="#cockpit-cache-func">cockpit.cache()</a></li>
<li><a href="#cockpit-cache-close">cache.close()</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_raw_channels">cockpit.js: Raw Channels</a>
<ul class="sectlevel3">
<li><a href="#cockpit-channels-channel">cockpit.channel()</a></li>
<li><a href="#cockpit-channels-binary">channel.binary</a></li>
<li><a href="#cockpit-channels-options">channel.options</a></li>
<li><a href="#cockpit-channels-valid">channel.valid</a></li>
<li><a href="#cockpit-channels-send">channel.send()</a></li>
<li><a href="#cockpit-channels-control">channel.control()</a></li>
<li><a href="#cockpit-channels-wait">channel.wait()</a></li>
<li><a href="#cockpit-channels-close">channel.close()</a></li>
<li><a href="#cockpit-channels-message">channel.onmessage</a></li>
<li><a href="#cockpit-channels-oncontrol">channel.oncontrol</a></li>
<li><a href="#cockpit-channels-onready">channel.onready</a></li>
<li><a href="#cockpit-channels-close-ev">channel.onclose</a></li>
<li><a href="#cockpit-transport-origin">cockpit.transport.origin</a></li>
<li><a href="#cockpit-transport-host">cockpit.transport.host</a></li>
<li><a href="#cockpit-transport-csrf-token">cockpit.transport.csrf_token</a></li>
<li><a href="#cockpit-transport-options">cockpit.transport.options</a></li>
<li><a href="#cockpit-transport-wait">cockpit.transport.wait()</a></li>
<li><a href="#cockpit-transport-close">cockpit.transport.close()</a></li>
<li><a href="#cockpit-transport-filter">cockpit.transport.filter()</a></li>
<li><a href="#cockpit-transport-inject">cockpit.transport.inject()</a></li>
<li><a href="#cockpit-base64-encode">cockpit.base64_encode()</a></li>
<li><a href="#cockpit-base64-decode">cockpit.base64_decode()</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_dbus_client">cockpit.js: DBus Client</a>
<ul class="sectlevel3">
<li><a href="#cockpit-dbus-types">DBus Types</a></li>
<li><a href="#cockpit-dbus-dbus">cockpit.dbus()</a></li>
<li><a href="#cockpit-dbus-wait">client.wait()</a></li>
<li><a href="#cockpit-dbus-close">client.close()</a></li>
<li><a href="#cockpit-dbus-onclose">client.onclose</a></li>
<li><a href="#cockpit-dbus-onowned">client.onowner</a></li>
<li><a href="#cockpit-dbus-options">client.options</a></li>
<li><a href="#cockpit-dbus-unique-name">client.unique_name</a></li>
<li><a href="#cockpit-dbus-proxy">client.proxy()</a></li>
<li><a href="#cockpit-dbus-proxy-client">proxy.client</a></li>
<li><a href="#cockpit-dbus-proxy-path">proxy.path</a></li>
<li><a href="#cockpit-dbus-proxy-iface">proxy.iface</a></li>
<li><a href="#cockpit-dbus-proxy-valid">proxy.valid</a></li>
<li><a href="#cockpit-dbus-proxy-data">proxy.data</a></li>
<li><a href="#cockpit-dbus-proxy-call">proxy.call()</a></li>
<li><a href="#cockpit-dbus-proxy-wait">proxy.wait()</a></li>
<li><a href="#cockpit-dbus-proxy-onchanged">proxy.onchanged</a></li>
<li><a href="#cockpit-dbus-proxy-signal">proxy.onsignal</a></li>
<li><a href="#cockpit-dbus-proxies">client.proxies()</a></li>
<li><a href="#cockpit-dbus-proxies-wait">proxies.wait()</a></li>
<li><a href="#cockpit-dbus-proxies-client">proxies.client</a></li>
<li><a href="#cockpit-dbus-proxies-iface">proxies.iface</a></li>
<li><a href="#cockpit-dbus-proxies-path_namespace">proxies.path_namespace</a></li>
<li><a href="#cockpit-dbus-proxies-onadded">proxies.onadded</a></li>
<li><a href="#cockpit-dbus-proxies-onchanged">proxies.onchanged</a></li>
<li><a href="#cockpit-dbus-proxies-onremoved">proxies.onremoved</a></li>
<li><a href="#cockpit-dbus-call">client.call()</a></li>
<li><a href="#cockpit-dbus-then">invocation.then()</a></li>
<li><a href="#cockpit-dbus-catch">invocation.catch()</a></li>
<li><a href="#cockpit-dbus-subscribe">client.subscribe()</a></li>
<li><a href="#cockpit-dbus-remove">subscription.remove()</a></li>
<li><a href="#cockpit-dbus-watch">client.watch()</a></li>
<li><a href="#cockpit-dbus-watch-then">watch.then()</a></li>
<li><a href="#cockpit-dbus-watch-catch">watch.catch()</a></li>
<li><a href="#cockpit-dbus-watch-remove">watch.remove()</a></li>
<li><a href="#cockpit-dbus-onnotify">client.onnotify</a></li>
<li><a href="#cockpit-dbus-notify">client.notify()</a></li>
<li><a href="#cockpit-dbus-onmeta">client.onmeta</a></li>
<li><a href="#cockpit-dbus-variant">cockpit.variant()</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_errors">cockpit.js: Errors</a>
<ul class="sectlevel3">
<li><a href="#cockpit-problems">Problem Codes</a></li>
<li><a href="#cockpit-messages">cockpit.message()</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_file_access">cockpit.js: File Access</a>
<ul class="sectlevel3">
<li><a href="#cockpit-file-simple">Simple reading and writing</a></li>
<li><a href="#cockpit-file-format">File format</a></li>
<li><a href="#cockpit-file-binary">Binary files</a></li>
<li><a href="#cockpit-file-atomic">Atomic modifications</a></li>
<li><a href="#cockpit-file-notify">Change notifications</a></li>
<li><a href="#cockpit-file-path">file.path</a></li>
<li><a href="#cockpit-file-close">Closing</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_http_client">cockpit.js: HTTP Client</a>
<ul class="sectlevel3">
<li><a href="#cockpit-http-constructor">cockpit.http()</a></li>
<li><a href="#cockpit-http-get">http.get()</a></li>
<li><a href="#cockpit-http-post">http.post()</a></li>
<li><a href="#cockpit-http-request">http.request()</a></li>
<li><a href="#cockpit-http-then">request.then()</a></li>
<li><a href="#cockpit-http-catch">request.catch()</a></li>
<li><a href="#cockpit-http-response">request.response()</a></li>
<li><a href="#cockpit-http-stream">request.stream()</a></li>
<li><a href="#cockpit-http-input">request.input()</a></li>
<li><a href="#cockpit-http-close">request.close()</a></li>
<li><a href="#cockpit-http-close-all">http.close()</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_localization">cockpit.js: Localization</a>
<ul class="sectlevel3">
<li><a href="#cockpit-locale-language">cockpit.language</a></li>
<li><a href="#cockpit-locale-locale">cockpit.locale()</a></li>
<li><a href="#cockpit-locale-gettext">cockpit.gettext()</a></li>
<li><a href="#cockpit-locale-noop">cockpit.noop()</a></li>
<li><a href="#cockpit-locale-ngettext">cockpit.ngettext()</a></li>
<li><a href="#cockpit-locale-translate">cockpit.translate()</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_page_location_and_jumping">cockpit.js: Page Location and Jumping</a>
<ul class="sectlevel3">
<li><a href="#cockpit-location-general">Page location</a></li>
<li><a href="#cockpit-jump">Jumping between components</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_user_session">cockpit.js: User Session</a>
<ul class="sectlevel3">
<li><a href="#cockpit-logout">cockpit.logout()</a></li>
<li><a href="#cockpit-user">cockpit.user()</a></li>
<li><a href="#cockpit-permission">Permission lookup</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_manifests">cockpit.js: Manifests</a>
<ul class="sectlevel3">
<li><a href="#cockpit-manifest-loading">Loading Manifests</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_metrics">cockpit.js: Metrics</a>
<ul class="sectlevel3">
<li><a href="#cockpit-metrics-function">cockpit.metrics()</a></li>
<li><a href="#cockpit-metrics-fetch">metrics.fetch()</a></li>
<li><a href="#cockpit-metrics-follow">metrics.follow()</a></li>
<li><a href="#cockpit-metrics-close">metrics.close()</a></li>
<li><a href="#cockpit-metrics-series">metrics.series</a></li>
<li><a href="#cockpit-metrics-meta">metrics.meta</a></li>
<li><a href="#cockpit-metrics-onchanged">metrics.onchanged</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_series_data">cockpit.js: Series Data</a>
<ul class="sectlevel3">
<li><a href="#cockpit-grid">cockpit.grid()</a></li>
<li><a href="#cockpit-grid-add">grid.add()</a></li>
<li><a href="#cockpit-grid-remove">grid.remove()</a></li>
<li><a href="#cockpit-grid-sync">grid.sync()</a></li>
<li><a href="#cockpit-grid-move">grid.move()</a></li>
<li><a href="#cockpit-grid-walk">grid.walk()</a></li>
<li><a href="#cockpit-grid-notify">grid.notify()</a></li>
<li><a href="#cockpit-grid-onnotify">grid.onnotify</a></li>
<li><a href="#cockpit-grid-close">grid.close()</a></li>
<li><a href="#cockpit-grid-interval">grid.interval</a></li>
<li><a href="#cockpit-grid-beg">grid.beg</a></li>
<li><a href="#cockpit-grid-end">grid.end</a></li>
<li><a href="#cockpit-series">cockpit.series()</a></li>
<li><a href="#cockpit-series-input">series.input()</a></li>
<li><a href="#cockpit-series-load">series.load()</a></li>
<li><a href="#cockpit-series-interval">series.interval</a></li>
<li><a href="#cockpit-series-limit">series.limit</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_spawning_processes">cockpit.js: Spawning Processes</a>
<ul class="sectlevel3">
<li><a href="#cockpit-spawn-spawn">cockpit.spawn()</a></li>
<li><a href="#cockpit-spawn-script">cockpit.script()</a></li>
<li><a href="#cockpit-spawn-then">process.then()</a></li>
<li><a href="#cockpit-spawn-catch">process.catch()</a></li>
<li><a href="#cockpit-spawn-stream">process.stream()</a></li>
<li><a href="#cockpit-spawn-input">process.input()</a></li>
<li><a href="#cockpit-spawn-close">process.close()</a></li>
</ul>
</li>
<li><a href="#_cockpit_js_utilities">cockpit.js: Utilities</a>
<ul class="sectlevel3">
<li><a href="#cockpit-format">cockpit.format()</a></li>
<li><a href="#cockpit-format-number">cockpit.format_number()</a></li>
<li><a href="#cockpit-format-bytes">cockpit.format_bytes()</a></li>
<li><a href="#cockpit-format-bytes-per-sec">cockpit.format_bytes_per_sec()</a></li>
<li><a href="#cockpit-format-bits-per-sec">cockpit.format_bits_per_sec()</a></li>
<li><a href="#cockpit-init">cockpit.init()</a></li>
<li><a href="#cockpit-info">cockpit.info</a></li>
<li><a href="#cockpit-event-target">cockpit.event_target</a></li>
</ul>
</li>
</ul>
</li>
<li><a href="#_api_shell">API: shell</a>
<ul class="sectlevel2">
<li><a href="#_index_html">index.html</a></li>
</ul>
</li>
<li><a href="#_api_system">API: system</a>
<ul class="sectlevel2">
<li><a href="#_logs_html">logs.html</a>
<ul class="sectlevel3">
<li><a href="#api-logs-html-description">Description</a></li>
</ul>
</li>
<li><a href="#_terminal_html">terminal.html</a>
<ul class="sectlevel3">
<li><a href="#api-terminal-html-description">Description</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div id="content">
<div class="sect1">
<h2 id="embedding">Embedding and Integrating Cockpit</h2>
<div class="sectionbody">
<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="sect2">
<h3 id="embedding-full">Embedding the Cockpit Interface</h3>
<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="sect2">
<h3 id="embedding-components">Integrating Cockpit Components into Web Applications</h3>
<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="sect2">
<h3 id="embedding-deep">Deep Integration</h3>
<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="sect2">
<h3 id="embedding-cors">Pinging Cockpit</h3>
<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>
<div class="sect1">
<h2 id="packages">Cockpit Packages</h2>
<div class="sectionbody">
<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="sect2">
<h3 id="package-layout">Layout of Package Files</h3>
<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="sect2">
<h3 id="_package_manifest">Package Manifest</h3>
<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="sect2">
<h3 id="package-manifest-override">Manifest overrides</h3>
<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="sect2">
<h3 id="package-links">Package Links and Paths</h3>
<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="sect2">
<h3 id="package-minified">Content Negotiation</h3>
<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="sect2">
<h3 id="package-api">Using Cockpit API</h3>
<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="sect2">
<h3 id="package-bridges">Bridges for specific tasks</h3>
<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="sect2">
<h3 id="package-replace">Replacing an existing package</h3>
<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>
<div class="sect1">
<h2 id="urls">Cockpit URLs</h2>
<div class="sectionbody">
<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="sect2">
<h3 id="urls-components">Component URLs</h3>
<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="sect2">
<h3 id="urls-visible">Visible URLs</h3>
<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>
<div class="sect1">
<h2 id="_api_base1">API: base1</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This package contains basic support API available to other packages.</p>
</div>
<div class="sect2">
<h3 id="_cockpit_js">cockpit.js</h3>
<div class="paragraph">
<p>Basic cockpit API to interact with the system</p>
</div>
<div class="sect3">
<h4 id="api-cockpit-loading">Loading cockpit.js</h4>
<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="sect2">
<h3 id="_cockpit_js_object_caching">cockpit.js: Object Caching</h3>
<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="sect3">
<h4 id="cockpit-cache-func">cockpit.cache()</h4>
<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="sect3">
<h4 id="cockpit-cache-close">cache.close()</h4>
<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="sect2">
<h3 id="_cockpit_js_raw_channels">cockpit.js: Raw Channels</h3>
<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="sect3">
<h4 id="cockpit-channels-channel">cockpit.channel()</h4>
<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="sect3">
<h4 id="cockpit-channels-binary">channel.binary</h4>
<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="sect3">
<h4 id="cockpit-channels-options">channel.options</h4>
<div class="paragraph">
<p>The options used to open this channel. This should not be changed.</p>
</div>
</div>
<div class="sect3">
<h4 id="cockpit-channels-valid">channel.valid</h4>
<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="sect3">
<h4 id="cockpit-channels-send">channel.send()</h4>
<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="sect3">
<h4 id="cockpit-channels-control">channel.control()</h4>
<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="sect3">
<h4 id="cockpit-channels-wait">channel.wait()</h4>
<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="sect3">
<h4 id="cockpit-channels-close">channel.close()</h4>
<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="sect3">
<h4 id="cockpit-channels-message">channel.onmessage</h4>
<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="sect3">
<h4 id="cockpit-channels-oncontrol">channel.oncontrol</h4>
<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="sect3">
<h4 id="cockpit-channels-onready">channel.onready</h4>
<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="sect3">
<h4 id="cockpit-channels-close-ev">channel.onclose</h4>
<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="sect3">
<h4 id="cockpit-transport-origin">cockpit.transport.origin</h4>
<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="sect3">
<h4 id="cockpit-transport-host">cockpit.transport.host</h4>
<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="sect3">
<h4 id="cockpit-transport-csrf-token">cockpit.transport.csrf_token</h4>
<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="sect3">
<h4 id="cockpit-transport-options">cockpit.transport.options</h4>
<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="sect3">
<h4 id="cockpit-transport-wait">cockpit.transport.wait()</h4>
<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="sect3">
<h4 id="cockpit-transport-close">cockpit.transport.close()</h4>
<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="sect3">
<h4 id="cockpit-transport-filter">cockpit.transport.filter()</h4>
<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="sect3">
<h4 id="cockpit-transport-inject">cockpit.transport.inject()</h4>
<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="sect3">
<h4 id="cockpit-base64-encode">cockpit.base64_encode()</h4>
<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="sect3">
<h4 id="cockpit-base64-decode">cockpit.base64_decode()</h4>
<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="sect2">
<h3 id="_cockpit_js_dbus_client">cockpit.js: DBus Client</h3>
<div class="paragraph">
<p>Cockpit allows access to DBus services via this API.</p>
</div>
<div class="sect3">
<h4 id="cockpit-dbus-types">DBus Types</h4>
<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="sect3">
<h4 id="cockpit-dbus-dbus">cockpit.dbus()</h4>
<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="sect3">
<h4 id="cockpit-dbus-wait">client.wait()</h4>
<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="sect3">
<h4 id="cockpit-dbus-close">client.close()</h4>
<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="sect3">
<h4 id="cockpit-dbus-onclose">client.onclose</h4>
<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="sect3">
<h4 id="cockpit-dbus-onowned">client.onowner</h4>
<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="sect3">
<h4 id="cockpit-dbus-options">client.options</h4>
<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="sect3">
<h4 id="cockpit-dbus-unique-name">client.unique_name</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxy">client.proxy()</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxy-client">proxy.client</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxy-path">proxy.path</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxy-iface">proxy.iface</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxy-valid">proxy.valid</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxy-data">proxy.data</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxy-call">proxy.call()</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxy-wait">proxy.wait()</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxy-onchanged">proxy.onchanged</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxy-signal">proxy.onsignal</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxies">client.proxies()</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxies-wait">proxies.wait()</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxies-client">proxies.client</h4>
<div class="paragraph">
<p>Set to the DBus client of the proxies. Will not change.</p>
</div>
</div>
<div class="sect3">
<h4 id="cockpit-dbus-proxies-iface">proxies.iface</h4>
<div class="paragraph">
<p>Set to the DBus interface name of the proxies. Will not change.</p>
</div>
</div>
<div class="sect3">
<h4 id="cockpit-dbus-proxies-path_namespace">proxies.path_namespace</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxies-onadded">proxies.onadded</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxies-onchanged">proxies.onchanged</h4>
<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="sect3">
<h4 id="cockpit-dbus-proxies-onremoved">proxies.onremoved</h4>
<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="sect3">
<h4 id="cockpit-dbus-call">client.call()</h4>
<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="sect3">
<h4 id="cockpit-dbus-then">invocation.then()</h4>
<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="sect3">
<h4 id="cockpit-dbus-catch">invocation.catch()</h4>
<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="sect3">
<h4 id="cockpit-dbus-subscribe">client.subscribe()</h4>
<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="sect3">
<h4 id="cockpit-dbus-remove">subscription.remove()</h4>
<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="sect3">
<h4 id="cockpit-dbus-watch">client.watch()</h4>
<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="sect3">
<h4 id="cockpit-dbus-watch-then">watch.then()</h4>
<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="sect3">
<h4 id="cockpit-dbus-watch-catch">watch.catch()</h4>
<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="sect3">
<h4 id="cockpit-dbus-watch-remove">watch.remove()</h4>
<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="sect3">
<h4 id="cockpit-dbus-onnotify">client.onnotify</h4>
<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="sect3">
<h4 id="cockpit-dbus-notify">client.notify()</h4>
<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="sect3">
<h4 id="cockpit-dbus-onmeta">client.onmeta</h4>
<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="sect3">
<h4 id="cockpit-dbus-variant">cockpit.variant()</h4>
<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="sect2">
<h3 id="_cockpit_js_errors">cockpit.js: Errors</h3>
<div class="paragraph">
<p>cockpit.js: Errors</p>
</div>
<div class="paragraph">
<p>Problem codes and messages</p>
</div>
<div class="sect3">
<h4 id="cockpit-problems">Problem Codes</h4>
<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="sect3">
<h4 id="cockpit-messages">cockpit.message()</h4>
<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="sect2">
<h3 id="_cockpit_js_file_access">cockpit.js: File Access</h3>
<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="sect3">
<h4 id="cockpit-file-simple">Simple reading and writing</h4>
<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="sect3">
<h4 id="cockpit-file-format">File format</h4>
<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="sect3">
<h4 id="cockpit-file-binary">Binary files</h4>
<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="sect3">
<h4 id="cockpit-file-atomic">Atomic modifications</h4>
<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="sect3">
<h4 id="cockpit-file-notify">Change notifications</h4>
<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="sect3">
<h4 id="cockpit-file-path">file.path</h4>
<div class="paragraph">
<p>A string containing the path that was passed to the <code>cockpit.file()</code>
method.</p>
</div>
</div>
<div class="sect3">
<h4 id="cockpit-file-close">Closing</h4>
<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="sect2">
<h3 id="_cockpit_js_http_client">cockpit.js: HTTP Client</h3>
<div class="paragraph">
<p>Cockpit allows access to local HTTP and REST services via this API.</p>
</div>
<div class="sect3">
<h4 id="cockpit-http-constructor">cockpit.http()</h4>
<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="sect3">
<h4 id="cockpit-http-get">http.get()</h4>
<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="sect3">
<h4 id="cockpit-http-post">http.post()</h4>
<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="sect3">
<h4 id="cockpit-http-request">http.request()</h4>
<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="sect3">
<h4 id="cockpit-http-then">request.then()</h4>
<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="sect3">
<h4 id="cockpit-http-catch">request.catch()</h4>
<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="sect3">
<h4 id="cockpit-http-response">request.response()</h4>
<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="sect3">
<h4 id="cockpit-http-stream">request.stream()</h4>
<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="sect3">
<h4 id="cockpit-http-input">request.input()</h4>
<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="sect3">
<h4 id="cockpit-http-close">request.close()</h4>
<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="sect3">
<h4 id="cockpit-http-close-all">http.close()</h4>
<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="sect2">
<h3 id="_cockpit_js_localization">cockpit.js: Localization</h3>
<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="sect3">
<h4 id="cockpit-locale-language">cockpit.language</h4>
<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="sect3">
<h4 id="cockpit-locale-locale">cockpit.locale()</h4>
<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="sect3">
<h4 id="cockpit-locale-gettext">cockpit.gettext()</h4>
<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="sect3">
<h4 id="cockpit-locale-noop">cockpit.noop()</h4>
<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="sect3">
<h4 id="cockpit-locale-ngettext">cockpit.ngettext()</h4>
<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="sect3">
<h4 id="cockpit-locale-translate">cockpit.translate()</h4>
<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="sect2">
<h3 id="_cockpit_js_page_location_and_jumping">cockpit.js: Page Location and Jumping</h3>
<div class="paragraph">
<p>Page location and navigation between components</p>
</div>
<div class="sect3">
<h4 id="cockpit-location-general">Page location</h4>
<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="sect4">
<h5 id="cockpit-location-href">location.href</h5>
<div class="paragraph">
<p>The string representation of this page location, including any options.</p>
</div>
</div>
<div class="sect4">
<h5 id="cockpit-location-path">location.path</h5>
<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="sect4">
<h5 id="cockpit-location-options">location.options</h5>
<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="sect4">
<h5 id="cockpit-location-go">location.go()</h5>
<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="sect4">
<h5 id="cockpit-location-replace">location.replace()</h5>
<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="sect4">
<h5 id="cockpit-location-decode">location.decode()</h5>
<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="sect4">
<h5 id="cockpit-location-encode">location.encode()</h5>
<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="sect4">
<h5 id="cockpit-location-changed">cockpit.onlocationchanged</h5>
<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="sect3">
<h4 id="cockpit-jump">Jumping between components</h4>
<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="sect4">
<h5 id="cockpit-jump-jump">cockpit.jump()</h5>
<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="sect4">
<h5 id="cockpit-jump-hidden">cockpit.hidden</h5>
<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="sect4">
<h5 id="cockpit-jump-visibilitychange">cockpit.onvisibilitychange</h5>
<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="sect2">
<h3 id="_cockpit_js_user_session">cockpit.js: User Session</h3>
<div class="paragraph">
<p>User information and login session state</p>
</div>
<div class="sect3">
<h4 id="cockpit-logout">cockpit.logout()</h4>
<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="sect3">
<h4 id="cockpit-user">cockpit.user()</h4>
<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="sect3">
<h4 id="cockpit-permission">Permission lookup</h4>
<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="sect4">
<h5 id="cockpit-permission-constructor">cockpit.permission()</h5>
<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="sect4">
<h5 id="cockpit-permission-allowed">permission.allowed</h5>
<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="sect4">
<h5 id="cockpit-permission-changed">permission.onchanged</h5>
<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="sect4">
<h5 id="cockpit-permission-close">permission.close()</h5>
<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="sect2">
<h3 id="_cockpit_js_manifests">cockpit.js: Manifests</h3>
<div class="sect3">
<h4 id="cockpit-manifest-loading">Loading Manifests</h4>
<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="sect2">
<h3 id="_cockpit_js_metrics">cockpit.js: Metrics</h3>
<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="sect3">
<h4 id="cockpit-metrics-function">cockpit.metrics()</h4>
<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="sect3">
<h4 id="cockpit-metrics-fetch">metrics.fetch()</h4>
<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="sect3">
<h4 id="cockpit-metrics-follow">metrics.follow()</h4>
<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="sect3">
<h4 id="cockpit-metrics-close">metrics.close()</h4>
<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="sect3">
<h4 id="cockpit-metrics-series">metrics.series</h4>
<div class="paragraph">
<p>The series sink where data retrieved data will be processed.</p>
</div>
</div>
<div class="sect3">
<h4 id="cockpit-metrics-meta">metrics.meta</h4>
<div class="paragraph">
<p>The metrics meta data last received.</p>
</div>
</div>
<div class="sect3">
<h4 id="cockpit-metrics-onchanged">metrics.onchanged</h4>
<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="sect2">
<h3 id="_cockpit_js_series_data">cockpit.js: Series Data</h3>
<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="sect3">
<h4 id="cockpit-grid">cockpit.grid()</h4>
<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="sect3">
<h4 id="cockpit-grid-add">grid.add()</h4>
<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="sect3">
<h4 id="cockpit-grid-remove">grid.remove()</h4>
<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="sect3">
<h4 id="cockpit-grid-sync">grid.sync()</h4>
<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="sect3">
<h4 id="cockpit-grid-move">grid.move()</h4>
<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="sect3">
<h4 id="cockpit-grid-walk">grid.walk()</h4>
<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="sect3">
<h4 id="cockpit-grid-notify">grid.notify()</h4>
<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="sect3">
<h4 id="cockpit-grid-onnotify">grid.onnotify</h4>
<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="sect3">
<h4 id="cockpit-grid-close">grid.close()</h4>
<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="sect3">
<h4 id="cockpit-grid-interval">grid.interval</h4>
<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="sect3">
<h4 id="cockpit-grid-beg">grid.beg</h4>
<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="sect3">
<h4 id="cockpit-grid-end">grid.end</h4>
<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="sect3">
<h4 id="cockpit-series">cockpit.series()</h4>
<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="sect3">
<h4 id="cockpit-series-input">series.input()</h4>
<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="sect3">
<h4 id="cockpit-series-load">series.load()</h4>
<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="sect3">
<h4 id="cockpit-series-interval">series.interval</h4>
<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="sect3">
<h4 id="cockpit-series-limit">series.limit</h4>
<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="sect2">
<h3 id="_cockpit_js_spawning_processes">cockpit.js: Spawning Processes</h3>
<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="sect3">
<h4 id="cockpit-spawn-spawn">cockpit.spawn()</h4>
<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="sect3">
<h4 id="cockpit-spawn-script">cockpit.script()</h4>
<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="sect3">
<h4 id="cockpit-spawn-then">process.then()</h4>
<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="sect3">
<h4 id="cockpit-spawn-catch">process.catch()</h4>
<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="sect3">
<h4 id="cockpit-spawn-stream">process.stream()</h4>
<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="sect3">
<h4 id="cockpit-spawn-input">process.input()</h4>
<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="sect3">
<h4 id="cockpit-spawn-close">process.close()</h4>
<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="sect2">
<h3 id="_cockpit_js_utilities">cockpit.js: Utilities</h3>
<div class="paragraph">
<p>Various utility functions</p>
</div>
<div class="sect3">
<h4 id="cockpit-format">cockpit.format()</h4>
<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="sect3">
<h4 id="cockpit-format-number">cockpit.format_number()</h4>
<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="sect3">
<h4 id="cockpit-format-bytes">cockpit.format_bytes()</h4>
<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="sect3">
<h4 id="cockpit-format-bytes-per-sec">cockpit.format_bytes_per_sec()</h4>
<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="sect3">
<h4 id="cockpit-format-bits-per-sec">cockpit.format_bits_per_sec()</h4>
<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="sect3">
<h4 id="cockpit-init">cockpit.init()</h4>
<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="sect3">
<h4 id="cockpit-info">cockpit.info</h4>
<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="sect3">
<h4 id="cockpit-event-target">cockpit.event_target</h4>
<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>
<div class="sect1">
<h2 id="_api_shell">API: shell</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This package contains the shell that loads other components.</p>
</div>
<div class="sect2">
<h3 id="_index_html">index.html</h3>
<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>
<div class="sect1">
<h2 id="_api_system">API: system</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This package contains general components for basic control of a system.</p>
</div>
<div class="sect2">
<h3 id="_logs_html">logs.html</h3>
<div class="paragraph">
<p>System log component</p>
</div>
<div class="sect3">
<h4 id="api-logs-html-description">Description</h4>
<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="sect2">
<h3 id="_terminal_html">terminal.html</h3>
<div class="paragraph">
<p>Server terminal component</p>
</div>
<div class="sect3">
<h4 id="api-terminal-html-description">Description</h4>
<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 id="footer">
<div id="footer-text">
Last updated 2026-01-28 11:12:25 UTC
</div>
</div>
</body>
</html>