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
|
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
<chapter id="embedding">
<title>Embedding and Integrating Cockpit</title>
<para>Cockpit can be embedded in other web applications either as a whole or specific
Cockpit components can be integrated.</para>
<section id="embedding-full">
<title>Embedding the Cockpit Interface</title>
<para>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></para>
<programlisting language="html"><![CDATA[
<html>
<head>
<title>Embedded Cockpit</title>
</head>
<body>
This is Cockpit.
<br/>
<iframe width="800px" height="600px"
src="https://server.example.com:9090/"/>
</body>
</html>
]]></programlisting>
</section>
<section id="embedding-components">
<title>Integrating Cockpit Components into Web Applications</title>
<para>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.</para>
<para>The component will load from the server in question and a WebSocket connection
will be established with the server to relay the component's message stream.</para>
<para>Cockpit components are HTML files contained in
<link linkend="packages">packages</link>. 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 <link linkend="development">API reference</link>. Each component URL begins with the string
<code>/cockpit/@localhost/</code> followed a package name, and then the component itself.</para>
<para>For example the
<link linkend="api-terminal-html">terminal.html</link> in the
<link linkend="api-system">system</link> package, has this URL:
<code>/cockpit/@localhost/system/terminal.html</code></para>
<programlisting language="html"><![CDATA[
<html>
<head>
<title>Embedded Terminal</title>
</head>
<body>
This is a terminal.
<br/>
<iframe width="800px" height="600px"
src="https://server.example.com:9090/cockpit/@localhost/system/terminal.html"/>
</body>
</html>
]]></programlisting>
</section>
<section id="embedding-deep">
<title>Deep Integration</title>
<para>Most often <link linkend="embedding-components">simple integration</link> 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's message stream to the server themselves.</para>
<warning>
<para>Deep integration capability is in heavy flux and is not yet documented.</para>
</warning>
</section>
<section id="embedding-cors">
<title>Pinging Cockpit</title>
<para>When embedding Cockpit or integrating Cockpit components, it may be necessary to check
whether Cockpit is available on a server before proceeding.</para>
<para>To do this perform a <code>/ping</code> request to Cockpit. This is a simple HTTP
GET request. It returns the following:</para>
<programlisting>
GET: https://server.example.com:9090/ping
200 OK: { "service": "cockpit" }
</programlisting>
<para>The <code>/ping</code> request allows
<ulink url="https://en.wikipedia.org/wiki/Cross-origin_resource_sharing">Cross Origin Resource Sharing</ulink>
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.</para>
<para>A complete example of using <code>/ping</code> is available in the Cockpit sources in the
<code>/examples/ping-server/</code> directory.</para>
</section>
</chapter>
|
