<?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="packages">
  <title>Cockpit Packages</title>

  <para>Cockpit is separated into various packages, each of which brings specific
    features and/or code.</para>

  <warning>
    <para>In addition, any APIs or behavior not explicitly documented here is an
      internal API and can be changed at any time.</para>
  </warning>

  <section id="package-layout">
    <title>Layout of Package Files</title>

    <para>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.</para>

    <para>The name of a package is the name of the directory.</para>

    <para>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.</para>

    <para>Cockpit uses the data directories from the
      <ulink url="https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG Base Directory
        Specification</ulink>
      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.</para>

    <para>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.</para>

    <para>This means that, by default the following directories are searched for cockpit packages, and
      in this order:</para>

    <itemizedlist>
      <listitem><para><code>~/.local/share/cockpit/</code></para></listitem>
      <listitem><para><code>/usr/local/share/cockpit/</code></para></listitem>
      <listitem><para><code>/usr/share/cockpit/</code></para></listitem>
    </itemizedlist>

    <para>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.</para>

    <para>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.</para>

<programlisting>
$ cockpit-bridge --packages
...
</programlisting>

    <para>To further clarify things, here is an example package called "my-package" and its file layout:</para>

<programlisting>
/usr/share/cockpit/
    my-package/
        manifest.json
        file.html
        some.js
</programlisting>

    <para>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.</para>

  </section>

  <section id="package-manifest">
    <title>Package Manifest</title>

    <para>Each package has a <code>manifest.json</code> file. It is a JSON object. The following
      fields may be present in the manifest:</para>

    <variablelist>
      <varlistentry>
        <term>content-security-policy</term>
        <listitem>
          <para>By default Cockpit serves packages using a strict
            <ulink url="https://en.wikipedia.org/wiki/Content_Security_Policy">Content Security Policy</ulink>,
            which among other things does not allow inline styles or scripts. This can
            be overridden on a per-package basis, with this setting.</para>
          <para>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.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>name</term>
        <listitem><para>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.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>priority</term>
        <listitem><para>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.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>requires</term>
        <listitem><para>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.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>version</term>
        <listitem><para>An informational version number for the package.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>preload</term>
        <listitem><para>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.
        </para><para>
        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.
        </para></listitem>
      </varlistentry>
    </variablelist>

    <para>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.)
    </para>

    <variablelist>
      <varlistentry>
        <term>dashboard</term>
        <listitem><para>Dashboard items appear in the menu under the section <emphasis>Apps</emphasis>.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>menu</term>
        <listitem><para>These items appear in the menu under the section <emphasis>System</emphasis>.
          This section is roughly ordered into these categories (with their
          <emphasis>order</emphasis> in parentheses):
          <itemizedlist>
            <listitem><para>System Information (10)</para></listitem>
            <listitem><para>Logs (20)</para></listitem>
            <listitem><para>Configuring major subsystems (30-40)</para></listitem>
            <listitem><para>Things running on the machine (VMs, Containers - 50-60)</para></listitem>
            <listitem><para>Implementation Details (Accounts, Services - 70-100)</para></listitem>
          </itemizedlist></para></listitem>
      </varlistentry>
      <varlistentry>
        <term>tools</term>
        <listitem><para>These items appear in the menu under the section <emphasis>Tools</emphasis>.
        </para></listitem>
      </varlistentry>
    </variablelist>

    <para>Menu items and tools are registered using JSON objects that have the
      following properties:</para>

    <variablelist>
      <varlistentry>
        <term>label</term>
        <listitem><para>The label for the menu item or tool.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>order</term>
        <listitem><para>An optional order number to place this menu item or tool. Lower numbers
          are listed first.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>path</term>
        <listitem><para>The relative path to the HTML file within the package that implements
          the menu item or tool.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>docs</term>
        <listitem><para>List of documentation URLs for the given page.
          Each item is an object containing <code>label</code> and <code>url</code>.
        </para></listitem>
      </varlistentry>
      <varlistentry>
        <term>keywords</term>
        <listitem><para>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.
        </para></listitem>
      </varlistentry>
    </variablelist>

    <para>Keyword items are registered using JSON objects that have the
      following properties:</para>

    <variablelist>
      <varlistentry>
        <term>matches</term>
        <listitem><para>List of keywords to be matched.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>goto</term>
        <listitem><para>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.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>weight</term>
        <listitem><para>How much keywords are prioritized over others. Default is 3.
          </para></listitem>
      </varlistentry>
      <varlistentry>
        <term>translate</term>
        <listitem><para><code>false</code> when keywords should not be localized. Default is <code>true</code>.
        </para></listitem>
      </varlistentry>
    </variablelist>

    <para>An example manifest.json with some optional properties set:</para>

<programlisting>
{
  "version": 0,
  "require": {
      "cockpit": "120"
  },
  "tools": {
     "mytool": {
        "label": "My Tool",
        "path": "tool.html"
     }
  }
}
</programlisting>

    <para>A file called <filename>override.json</filename> may be placed next to the manifest.
      containing overrides to the information in the manifest. These override files are in the
      simple <ulink url="https://tools.ietf.org/html/rfc7386">JSON Merge Patch</ulink> format.</para>

  </section>

  <section id="package-links">
    <title>Package Links and Paths</title>

    <para>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.</para>

    <para>For example here's how to include the base <code>cockpit.js</code> script in your HTML
      from the <code>latest</code> package:</para>

<programlisting>
&lt;script src="../base1/cockpit.js"&gt;&lt;/script&gt;
</programlisting>

    <para>Do not assume you can link to any file in any other package. Refer to the
      <link linkend="development">list of API packages</link> for those that are
      available for use.</para>
  </section>

  <section id="package-minified">
    <title>Content Negotiation</title>

    <para>In order to support language specific files, gzipped and/or minified data, the
      files in a package are loaded using content negotiation logic.</para>

    <para>If a file does not exist at the expected path, Cockpit tries to insert
      <code>.min</code> before its extension. It also tries adding a <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.</para>

    <para>This means that for the file <code>test.de.js</code> in the package named
      <code>mypackage</code> the following files would be tried in this order:</para>

<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
</programlisting>

    <para>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.</para>
  </section>

  <section id="package-api">
    <title>Using Cockpit API</title>

    <para>Cockpit has API available for writing packages. There is no API available
      for external callers to invoke via HTTP, REST or otherwise.</para>

    <para>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.</para>

    <itemizedlist>
      <listitem><para><link linkend="development">API Listing</link></para></listitem>
    </itemizedlist>

    <para>To include javascript from the API, simply load it into your HTML using
      a script tag. Alternatively you can use an javascript loader.</para>
  </section>

  <section id="package-bridges">
    <title>Bridges for specific tasks</title>

    <para>On the server side the
      <link linkend="cockpit-bridge.1"><filename>cockpit-bridge</filename></link> connects
      to various system APIs that the front end UI requests it to. There are additional
      bridges for specific tasks that the main <filename>cockpit-bridge</filename> cannot
      handle, such as using the PCP C library API.</para>

    <para>These additional bridges can be registered in a <code>"bridges"</code> section of a
      package's <filename>manifest.json</filename> 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.</para>

    <para>An example <filename>manifest.json</filename> with a bridges section:</para>

<programlisting>
{
    "bridges": [
        {
            "match": { "payload": "metrics1" },
            "spawn": [ "/usr/libexec/cockpit-pcp" ]
        }
    ]
}
</programlisting>

    <para>The bridges are considered in the order they are listed in the array. Use the
      <filename>manifest.json</filename><code>"priority"</code> field to control order between
      packages. The bridges are registered using JSON objects that have the following
      properties:</para>

    <variablelist>
      <varlistentry>
        <term>environ</term>
        <listitem><para>Optional, additional environment variables to pass to the bridge
            command.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>match</term>
        <listitem><para>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.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>privileged</term>
        <listitem><para>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.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>problem</term>
        <listitem><para>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.</para></listitem>
      </varlistentry>
      <varlistentry>
        <term>spawn</term>
        <listitem><para>The command and arguments to invoke.</para></listitem>
      </varlistentry>
    </variablelist>

    <para>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></para>

    <para>For example a bridges section like:</para>
<programlisting>
{
  "bridges": [
    {
      "match": { "payload": "example" },
      "environ": [ "TAG=${tag}" ],
      "spawn: [ "/example-bridge", "--tag", "${tag}" ],
      "problem": "access-denied"
    }
  ]
}
</programlisting>

    <para>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</para>

    <programlisting>TAG=tag1 /example-bridge --tag tag1</programlisting>

    <para>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:</para>

    <programlisting>TAG=tag2 /example-bridge --tag tag2</programlisting>

    <para>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></para>

  </section>

  <section id="package-replace">
    <title>Replacing an existing package</title>

    <para>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>.</para>

    <para>For example, a package in the <filename>/usr/share/cockpit/disks</filename>
      directory could replace Cockpit's <emphasis>storage</emphasis> package with
      a <filename>manifest.json</filename> like this:</para>

<programlisting>
{
  "version": 0,
  "name": "storage",
  "priority": 10,
  "menu": {
     "index": {
        "label": "Disk Storage",
        "order": 15
     }
  }
}
</programlisting>

    <para>It is also possible to hide or change labels on the menu items of an existing
      package by including a <filename>override.json</filename> in that existing package's
      directory.</para>

    <para>For example an <filename>/usr/share/cockpit/systemd/override.json</filename> could
      hide the <emphasis>Logs</emphasis> menu item and move the <emphasis>Services</emphasis>
      menu item to the top of the menu.</para>

<programlisting>
{
  "menu": {
    "logs": null,
    "services": {
      "order": -1
    }
  }
}
</programlisting>

  </section>

</chapter>