/usr/share/doc/cockpit/guide/packages.html is in cockpit-doc 164-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Cockpit Packages</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Cockpit Guide">
<link rel="up" href="development.html" title="Part III. Developer Guide">
<link rel="prev" href="embedding.html" title="Embedding and Integrating Cockpit">
<link rel="next" href="urls.html" title="Cockpit URLs">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle">
<td><a accesskey="p" href="embedding.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
<td><a accesskey="u" href="development.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
<th width="100%" align="center">Cockpit Guide</th>
<td><a accesskey="n" href="urls.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="packages"></a>Cockpit Packages</h2></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="packages.html#package-layout">Layout of Package Files</a></span></dt>
<dt><span class="section"><a href="packages.html#package-manifest">Package Manifest</a></span></dt>
<dt><span class="section"><a href="packages.html#package-links">Package Links and Paths</a></span></dt>
<dt><span class="section"><a href="packages.html#package-minified">Content Negotiation</a></span></dt>
<dt><span class="section"><a href="packages.html#package-api">Using Cockpit API</a></span></dt>
<dt><span class="section"><a href="packages.html#package-bridges">Bridges for specific tasks</a></span></dt>
<dt><span class="section"><a href="packages.html#package-replace">Replacing an existing package</a></span></dt>
</dl></div>
<p>Cockpit is separated into various packages, each of which brings specific
features and/or code.</p>
<div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
<h3 class="title">Warning</h3>
<p>In addition, any APIs or behavior not explicitly documented here is an
internal API and can be changed at any time.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="package-layout"></a>Layout of Package Files</h2></div></div></div>
<p>A package consists of one or more files placed in a directory or its
subdirectories. It must have a <code class="code">manifest.json</code> file and follow
certain naming conventions.</p>
<p>The name of a package is the name of the directory.</p>
<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>
<p>Cockpit uses the data directories from the
<a class="ulink" href="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html" target="_top">XDG Base Directory
Specification</a>
to locate packages. The <code class="code">$XDG_DATA_DIRS</code> represents a colon separate list of system data
directories, and <code class="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 class="code">--prefix=/path</code> then the <code class="code">$prefix/share/cockpit</code> is used by
default.</p>
<p>A <code class="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 class="code">$XDG_DATA_HOME</code> and then <code class="code">$XDG_DATA_DIRS</code> in order.</p>
<p>This means that, by default the following directories are searched for cockpit packages, and
in this order:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><code class="code">~/.local/share/cockpit/</code></p></li>
<li class="listitem"><p><code class="code">/usr/local/share/cockpit/</code></p></li>
<li class="listitem"><p><code class="code">/usr/share/cockpit/</code></p></li>
</ul></div>
<p>Packages placed in <code class="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>
<p>You can use the following command to list the packages installed on a server. You'll note that
it's output may change when you run the command as different users, if there are packages installed
in the user's home directory.</p>
<pre class="programlisting">
$ cockpit-bridge --packages
...
</pre>
<p>To further clarify things, here is an example package called "my-package" and its file layout:</p>
<pre class="programlisting">
/usr/share/cockpit/
my-package/
manifest.json
file.html
some.js
</pre>
<p>Place or symlink packages in your <code class="code">~/.local/share/cockpit</code> directory (or appropriate
<code class="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 class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="package-manifest"></a>Package Manifest</h2></div></div></div>
<p>Each package has a <code class="code">manifest.json</code> file. It is a JSON object. The following
fields may be present in the manifest:</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term">content-security-policy</span></p></td>
<td>
<p>By default Cockpit serves packages using a strict
<a class="ulink" href="https://en.wikipedia.org/wiki/Content_Security_Policy" target="_top">Content Security Policy</a>,
which among other things does not allow inline styles or scripts. This can
be overriden on a per-package basis, with this setting.</p>
<p>If the overriden content security policy does not contain a <code class="code">default-src</code>,
<code class="code">connect-src</code>, <code class="code">base-uri</code>, <code class="code">form-action</code>, <code class="code">object-src</code>,
or <code class="code">block-all-mixed-content</code> then these will be added to the policy from the manifest.</p>
</td>
</tr>
<tr>
<td><p><span class="term">dashboard</span></p></td>
<td><p>An optional JSON object containing any dashboard items that this package
provides. These will be added into the Cockpit user interface on the top bar.
Each property on this object is named for the identifier of such an item, and the
property value is a JSON object described below.</p></td>
</tr>
<tr>
<td><p><span class="term">menu</span></p></td>
<td><p>An optional JSON object containing any main menu items that this package
provides. These will be added into the Cockpit user interface on the side bar.
Each property on this object is named for the identifier of such an item, and the
property value is a JSON object described below.</p></td>
</tr>
<tr>
<td><p><span class="term">name</span></p></td>
<td><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></td>
</tr>
<tr>
<td><p><span class="term">priority</span></p></td>
<td><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 class="code">name</code> a package is chosen based on its priority.</p></td>
</tr>
<tr>
<td><p><span class="term">requires</span></p></td>
<td><p>An optional JSON object that contains a <code class="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></td>
</tr>
<tr>
<td><p><span class="term">tools</span></p></td>
<td><p>An optional JSON object containing all the tools that this package
provides. These will be added into the Cockpit user interface under the 'Tools' menu.
Each property on this object is named for the identifier of such a tool, and the
property value is a JSON object described below.</p></td>
</tr>
<tr>
<td><p><span class="term">version</span></p></td>
<td><p>An informational version number for the package.</p></td>
</tr>
</tbody>
</table></div>
<p>Menu items and tools are registered using JSON objects that have the
following properties:</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term">label</span></p></td>
<td><p>The label for the menu item or tool.</p></td>
</tr>
<tr>
<td><p><span class="term">order</span></p></td>
<td><p>An optional order number to place this menu item or tool. Lower numbers
are listed first.</p></td>
</tr>
<tr>
<td><p><span class="term">path</span></p></td>
<td><p>The relative path to the HTML file within the package that implements
the menu item or tool.</p></td>
</tr>
</tbody>
</table></div>
<p>An example manifest.json with some optional properties set:</p>
<pre class="programlisting">
{
"version": 0,
"require": {
"cockpit": "120"
},
"tools": {
"mytool": {
"label": "My Tool",
"path": "tool.html"
}
}
}
</pre>
<p>A file called <code class="filename">override.json</code> may be placed next to the manifest.
containing overrides to the information in the manifest. These override files are in the
simple <a class="ulink" href="https://tools.ietf.org/html/rfc7386" target="_top">JSON Merge Patch</a> format.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="package-links"></a>Package Links and Paths</h2></div></div></div>
<p>When referring to files in your package, such as in a hyperlink or a <code class="code"><style></code>
tag or <code class="code"><script></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>
<p>For example here's how to include the base <code class="code">cockpit.js</code> script in your HTML
from the <code class="code">latest</code> package:</p>
<pre class="programlisting">
<script src="../base1/cockpit.js"></script>
</pre>
<p>Do not assume you can link to any file in any other package. Refer to the
<a class="link" href="development.html" title="Part III. Developer Guide">list of API packages</a> for those that are
available for use.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="package-minified"></a>Content Negotiation</h2></div></div></div>
<p>In order to support language specific files, gzipped and/or minified data, the
files in a package are loaded using content negotiation logic.</p>
<p>If a file does not exist at the expected path, Cockpit tries to insert
<code class="code">.min</code> before its extension. It also tries adding a <code class="code">.gz</code>
to both of those file names. If the file is still not found, and the request path has
more than one extension, the second to the last extension is popped off, and the above
process repeats.</p>
<p>This means that for the file <code class="code">test.de.js</code> in the package named
<code class="code">mypackage</code> the following files would be tried in this order:</p>
<pre class="programlisting">
mypackage/test.de.js
mypackage/test.de.min.js
mypackage/test.de.js.gz
mypackage/test.de.min.js.gz
mypackage/test.js
mypackage/test.min.js
mypackage/test.js.gz
mypackage/test.min.js.gz
</pre>
<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 class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="package-api"></a>Using Cockpit API</h2></div></div></div>
<p>Cockpit has API available for writing packages. There is no API available
for external callers to invoke via HTTP, REST or otherwise.</p>
<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 class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="link" href="development.html" title="Part III. Developer Guide">API Listing</a></p></li></ul></div>
<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 class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="package-bridges"></a>Bridges for specific tasks</h2></div></div></div>
<p>On the server side the
<GTKDOCLINK HREF="cockpit-bridge.1"><code class="filename">cockpit-bridge</code></GTKDOCLINK> connects
to various system APIs that the front end UI requests it to. There are additional
bridges for specific tasks that the main <code class="filename">cockpit-bridge</code> cannot
handle. For example tasks that should be carried out with privilege escalation.</p>
<p>These additional bridges can be registered in a <code class="code">"bridges"</code> section of a
package's <code class="filename">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'll look at how they are registered.</p>
<p>An example <code class="filename">manifest.json</code> with a bridges section:</p>
<pre class="programlisting">
{
"bridges": [
{
"match": { "superuser": null },
"environ": [ "SUDO_ASKPASS=/usr/bin/my-password-tool" ],
"spawn: [ "/usr/bin/sudo", "-n", "cockpit-bridge", "--privileged" ],
"problem": "access-denied"
}
]
}
</pre>
<p>The bridges are considered in the order they are listed in the array. Use the
<code class="filename">manifest.json</code><code class="code">"priority"</code> field to control order between
packages. The bridges are registered using JSON objects that have the following
properties:</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term">environ</span></p></td>
<td><p>Optional, additional environment variables to pass to the bridge
command.</p></td>
</tr>
<tr>
<td><p><span class="term">match</span></p></td>
<td><p>The <code class="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></td>
</tr>
<tr>
<td><p><span class="term">problem</span></p></td>
<td><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></td>
</tr>
<tr>
<td><p><span class="term">spawn</span></p></td>
<td><p>The command and arguments to invoke.</p></td>
</tr>
</tbody>
</table></div>
<p>The <code class="code">spawn</code> and <code class="code">environ</code> values can be dynamically
taken from a matching open command values. When a value in either the <code class="code">spawn</code>
or <code class="code">environ</code> array contains a named variable wrapped in <code class="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 class="code">._-</code></p>
<p>For example a bridges section like:</p>
<pre class="programlisting">
{
"bridges": [
{
"match": { "payload": "example" },
"environ": [ "TAG=${tag}" ],
"spawn: [ "/example-bridge", "--tag", "${tag}" ],
"problem": "access-denied"
}
]
}
</pre>
<p>when a open command is received with a payload of <code class="code">example</code>
with <code class="code">tag</code> value of <code class="code">tag1</code>. The following
command will be spawned</p>
<pre class="programlisting">TAG=tag1 /example-bridge --tag tag1</pre>
<p>Processes that are reused so if another open command with a "tag" of
<code class="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 class="code">tag2</code> will spawn a new command:</p>
<pre class="programlisting">TAG=tag2 /example-bridge --tag tag2</pre>
<p>If you need to include <code class="code">${}</code>, as an actual value in your arguments
you can escape it by prefixing it with a <code class="code">\</code></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="package-replace"></a>Replacing an existing package</h2></div></div></div>
<p>If the functionality in a package replaces that of another package
then it can replace that package by claiming the same <code class="code">name</code> and a
higher <code class="code">priority</code>.</p>
<p>For example, a package in the <code class="filename">/usr/share/cockpit/disks</code>
directory could replace Cockpit's <span class="emphasis"><em>storage</em></span> package with
a <code class="filename">manifest.json</code> like this:</p>
<pre class="programlisting">
{
"version": 0,
"name": "storage",
"priority": 10,
"menu": {
"index": {
"label": "Disk Storage",
"order": 15
}
}
}
</pre>
<p>It is also possible to hide or change labels on the menu items of an existing
package by including a <code class="filename">override.json</code> in that existing package's
directory.</p>
<p>For example an <code class="filename">/usr/share/cockpit/systemd/override.json</code> could
hide the <span class="emphasis"><em>Logs</em></span> menu item and move the <span class="emphasis"><em>Services</em></span>
menu item to the top of the menu.</p>
<pre class="programlisting">
{
"menu": {
"logs": null,
"services": {
"order": -1
}
}
}
</pre>
</div>
</div>
<div class="footer"><hr></div>
</body>
</html>
|