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
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
|
<!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 Vsnapshot">
<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="https://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 overridden on a per-package basis, with this setting.</p>
<p>If the overridden 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">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">version</span></p></td>
<td><p>An informational version number for the package.</p></td>
</tr>
<tr>
<td><p><span class="term">preload</span></p></td>
<td>
<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.
</p>
<p>
The value of this field is an array of strings, where each
string is one of the keys used in the <code class="code">dashboard</code>,
<code class="code">menu</code>, or <code class="code">tool</code> fields that are
explained below.
</p>
</td>
</tr>
</tbody>
</table></div>
<p>In addition, the following keys contain information about where components of the package
should appear in Cockpit'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't perfectly match the current user interface for historical reasons.)
</p>
<div class="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term">dashboard</span></p></td>
<td><p>Dashboard items appear in the menu under the section <span class="emphasis"><em>Apps</em></span>.</p></td>
</tr>
<tr>
<td><p><span class="term">menu</span></p></td>
<td>
<p>These items appear in the menu under the section <span class="emphasis"><em>System</em></span>.
This section is roughly ordered into these categories (with their
<span class="emphasis"><em>order</em></span> in parentheses):
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>System Information (10)</p></li>
<li class="listitem"><p>Logs (20)</p></li>
<li class="listitem"><p>Configuring major subsystems (30-40)</p></li>
<li class="listitem"><p>Things running on the machine (VMs, Containers - 50-60)</p></li>
<li class="listitem"><p>Implementation Details (Accounts, Services - 70-100)</p></li>
</ul></div>
</td>
</tr>
<tr>
<td><p><span class="term">tools</span></p></td>
<td><p>These items appear in the menu under the section <span class="emphasis"><em>Tools</em></span>.
</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>
<tr>
<td><p><span class="term">docs</span></p></td>
<td><p>List of documentation URLs for the given page.
Each item is an object containing <code class="code">label</code> and <code class="code">url</code>.
</p></td>
</tr>
<tr>
<td><p><span class="term">keywords</span></p></td>
<td><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></td>
</tr>
</tbody>
</table></div>
<p>Keyword items 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">matches</span></p></td>
<td><p>List of keywords to be matched.</p></td>
</tr>
<tr>
<td><p><span class="term">goto</span></p></td>
<td><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 class="code">goto:"page_hash"</code> in page with <code class="code">path:"/page_path"</code>
would redirect to <code class="code">/page_path#page_hash</code>, while <code class="code">goto:"/page_path"</code>
would redirect to <code class="code">/page_path</code> ignoring default page path.</p></td>
</tr>
<tr>
<td><p><span class="term">weight</span></p></td>
<td><p>How much keywords are prioritized over others. Default is 3.
</p></td>
</tr>
<tr>
<td><p><span class="term">translate</span></p></td>
<td><p><code class="code">false</code> when keywords should not be localized. Default is <code class="code">true</code>.
</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, such as using the PCP C library API.</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": { "payload": "metrics1" },
"spawn": [ "/usr/libexec/cockpit-pcp" ]
}
]
}
</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">privileged</span></p></td>
<td><p>If set to <code class="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 class="code">"match"</code> property.</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>
|
