Cockpit Project - Tutorial

Pixel testing update

Thu, 03 Feb 2022 10:00:00 +0000

Since May last year, the Cockpit integration tests contain “pixel tests”, as described here. Let’s have a look at what has happened since then.

Mobile layout

Katerina has made it so that all our integration tests run with two sizes of the browser: one time with the old “desktop” size (1920x1280), and again with a “mobile” size (414x1920). This has forced us to look more closely at how Cockpit behaves in such a narrow screen, and we have since fixed it up quite a bit.

Before this, we had relied on people manually testing Cockpit in a mobile layout. This was done occasionally, but now the mobile layout is almost a first class citizen, and I am certain we will keep fixing Cockpit until we are fully happy with it. My feeling is that this would not have happened without automated pixel testing.

A recent example is this pull request. We did know about the broken mobile layout of the images list, but the thing that kicked us to actually fix it was the enabling of “mobile” pixel tests in the cockpit-podman repository. Having to commit a obviously terrible reference image is unpleasant enough to finally sit down and fix the thing.

Of course, it helped that we had enough experience from fixing the mobile layout of Cockpit, and that’s how the rising tide lifts all the boats: Soon everyone in the team will not only care about the mobile layout, but also know how to fix any issues with it. We have managed to push the mobile layout over the threshold where it becomes rewarding to keep it in good shape, instead of it being so annyoing that we would rather ignore it.

Some numbers

Right now, we have 52 pixel tests in Cockpit itself, 20 in Cockpit-machines, and 5 in Cockpit-podman. Each pixel test has a reference image for three layouts, so we have 231 of them, totalling about 10 MiB. The Git repository with all their history is about 22 MiB, for nine months of pixel testing. (The main Cockpit repository is about 110 MiB, for about nine years of hacking.)

Pixel tests are kind of slow, up to a few seconds per image comparison. They might increase the running time of our tests by a couple of minutes. We will have to measure this more carefully.

Reproducing pixels

Unsurprisingly, it is non-trivial to make sure that the integration tests always perform a given pixel test with exactly the same result. We know that we had to battle rendering issues from the start, but it took us a bit to figure out the following:

Elements need to be scrolled into view before we can test their pixels. Obvious, but it needed to actually happen before we realized it.
There are some animations, and we need to make sure that we don’t take a pixel test mid-animation.
When the Shell of Cockpit is changed, the content area for pages like Networking might change size. This is a problem for external projects that don’t control the version of the Cockpit shell. We worked around this by giving the content iframe a fixed size (by making the browser window slightly bigger or smaller if necessary).
We would miss failed pixels when a test ran into a known issue. A known issue would cause the test to be skipped, and one would have to look very closely to spot that it also had a failing pixel test. This means that we sometimes forgot to update some reference images, and would later be surprised by how we could have missed them.
As we change tests, we would accumulate unused reference images. The bots now force us to clean up properly.
Even though the actual DOM rendering is suprisingly deterministic, one or two pixels in a million still come out slightly differently, from time to time. We have no better idea but to allow a low number of imperfections per pixel test.

With every change, we are more certain that we can get the pixel test costs under control. We might never reach a point where we can stop tweaking the pixel test machinery, but the same is true about our CI testing machinery in general.

Why don’t we hate them?

I was expecting that adding pixel tests to Cockpit would be a hard sell, but we all seem to like them. That’s awesome! What a team!

I was afraid that pixel tests would be very unreliable because browsers would not be nearly pixel perfect enough. But it turns out that they are very good at this, actually, even across versions. We had to switch off font hinting, and results are not consistent between running the tests locally and runnning them in the cloud, but pixels are almost never changing randomly from one run to the next.

The unreliability comes mostly from not getting the DOM into the exact same state every time a given pixel test runs. This has always been a problem with our tests and we are pretty good at dealing with it.

However, while the traditional tests were just code in the main repo, pixel tests are binary files in a Git submodule. Submodules can be very confusing, and we tried to hide most of it behind a script. And Github is actually pretty good with images.

One thing we have learned is to update reference images only very late in the life of a pull request. Resolving merge conflicts of binary files in a submodule is just not fun.

I think we all like them because the value that we derive from pixel tests is well worth their cost. It feels awesome to officially replace an image of a sucky part of Cockpit with a nice one while fixing the code, and to show off a new feature with a couple of screenshots that you know will be kept from regressing.

The original goal, updating Patternfly and not having to worry about missing visual regressions, has been reached.

So I would say the future looks good for pixel tests. We are still adding more, and we have recently added a whole new browser size with it’s own set of 77 new reference images. We keep them working, and they keep Cockpit pretty and us honest.

I count that as a success! And a lot of thanks to the team for being so willing to experiment. Especially to Katerina for being even more excited about pixel tests in the beginning than I was. 😁

Testing all the pixels

Thu, 06 May 2021 10:00:00 +0000

The Cockpit integration tests can now contain “pixel tests”. Such a test will take a screenshot with the browser and compare it with a reference. The idea is that we can catch visual regressions much easier this way than if we would hunt for them in a purely manual fashion.

Preparing a repository for pixel tests

A pixel test will take a screenshot of part of the Cockpit UI and compare it with a reference. Thus, these reference images are important and play the biggest role.

A large part of dealing with pixel tests will consequently consist of maintaining the reference images. At the same time, we don’t want to clog up our main source repository with them. While the number and size of the reference images at any one point in time should not pose a problem, we will over time accumulate a history of them that we are afraid would dominate the source repository.

Thus, the reference images are not stored in the source repository. Instead, we store them in an external repository that is linked into the source repository as a submodule. That external repository doesn’t keep any history and can be aggressively pruned.

Developers are mostly isolated from this via the new test/common/pixel-tests tool. But if you are familiar with git submodules, there should be no surprises for you here.

A source repository needs to be prepared before it can store reference images in a external storage repository. You can let the tool do it by running

$ ./test/common/pixel-tests init

and then committing the changes it has done to the source repository. (Those changes will be a new or modified .gitmodules file, and a new gitlink at test/reference.)

Adding a pixel test

To add a pixel test to a test program, call the new “assert_pixels” function of the Browser class:

    def testSomeDialog(self):
        ...
        self.browser.assert_pixels('#dialog button.apply', "button")
        ...

The first argument is a CSS selector that identifies the part of the UI that you want to compare. The screenshot will only include that element. The second argument is an arbitrary but unique key for this test point. It is used to name the files that go with it.

For each such call, there needs to be a reference image in the test/reference/ directory.

As mentioned above, the test/reference/ directory is very special indeed, and needs to be carefully managed with the test/common/pixel-tests tool (or even more carefully with git submodule et al).

First, make sure test/reference is up-to-date:

$ ./test/common/pixel-tests pull

Then you can add new reference images to it.

The easiest way to get a new reference image is to just run the test once (locally or in the CI machinery). It will fail, but produce a reference image for the current state of the UI.

When you run the test locally, the new reference image will appear in the current directory. Just move it into test/reference/. The next run of the test should then be green.

When you run the tests in the CI machinery, you need to download the new reference images from the test results directory. They show up as regular screenshots.

If there are parts of the reference image that you want to ignore, you can pass a suitable “ignore” argument to assert_pixels. It contains a list of CSS selectors, and any pixel that is within their bounding rectangles is ignored. For example, this

    def testSomeDialog(self):
        ...
        self.browser.assert_pixels('#dialog', "dialog", ignore=["#memory-available"])
        ...

would compare a full dialog to a reference, but would exclude the DOM element that shows a number that is dependent on the environment that the test runs in.

You can also change the transparency (alpha channel) of parts of the reference image itself (with the GIMP, say). Any pixel that is not fully opaque will be ignored during comparison.

When you are done adding images to test/reference, push them into the storage repository like so:

$ ./test/common/pixel-tests push

This push command will record a change to test/reference in the main repository, and you need to commit this change. This is how the main repository specifies which reference images to use exactly for each of its commits.

If you want to see what changes would be pushed without actually pushing them, you can run this:

$ ./test/common/pixel-tests status

Here is a PR that adds two pixel test points to the starter-kit, complete with reference images:

starter-kit#436

Debugging a failed pixel test

When making changes that change how the UI looks, some pixel tests will fail. The test results will contain the new pixels, and you can compare them with the reference image right in the browser when looking at the test logs.

Here is a PR that makes the two pixel tests fail that had been added in #436:

starter-kit#435

As you can see, it has “changed pixels” links in the same place as the well known “screenshot” links. Clicking on it gets you to a page where you can directly compare the previous and current UI.

As the author of the pull request, you can decide from there whether these changes are intended or not.

For a intended change, see the next section. For unintended changes, you need to fix your code and try again, of course.

Updating a pixel test

If you make a change that intentionally changes how Cockpit looks, you need to install new reference images in test/reference/.

This is very similar to adding a new pixel test point. Take the TestFoo-testBasic-pixels.png that was written by the failed test run, move it into test/reference, push it to the storage repository with ./test/common/pixel-tests push, and commit test/reference in the main repository.

A local test run has dropped the new reference image into the current directory, for a remote run it will be in the test results directory and the pixel comparison view has a link to it.

When a test writes a new TestFoo-testBasic-pixels.png file for a failed test, it will have the alpha channel of the old reference copied into it. That makes it easy to keep ignoring the same parts.

Reviewing a changed pixel test

Here is a second version of the starter-kit pull request from the previous section:

starter-kit#438

It has the same code changes, but now the reference images have been updated as well, since the change in color was of course intended.

Now this PR needs to be reviewed, and the changed visuals need to be approved. But since the reference images are not stored in the main repository, Github will not include them in the PR diff view.

Instead, the robots will automatically add a comment to a pull request with a link to a page that allows reviewing the changed reference images.

Creating Plugins for the Cockpit User Interface

Mon, 04 May 2020 00:00:00 +0000

Note: This post was updated in Aug 2022 to adjust to reflect Cockpit UI and development best practices.

Cockpit is a web-based graphical interface for servers. You can easily add your own custom pages to the navigation.

For this tutorial you need to install your distribution’s cockpit packages or build it from git.

We’ll make a package called pinger that checks whether your server has network connectivity to the Internet by pinging another host. It’s simple and not too fancy. The package will spawn a process on the server to do all the work.

This example package is already included in the Cockpit sources. You can look it over and modify it.

To start, let’s get ready for development by launching a terminal on your local computer.

First, create a project directory and download the example:

mkdir pinger; cd pinger
curl -O https://raw.githubusercontent.com/cockpit-project/cockpit/master/examples/pinger/manifest.json
curl -O https://raw.githubusercontent.com/cockpit-project/cockpit/master/examples/pinger/ping.html
curl -O https://raw.githubusercontent.com/cockpit-project/cockpit/master/examples/pinger/pinger.js

Cockpit pages — more specifically their HTML and Javascript files — live in package directories. In the package directory there’s also a manifest.json file which tells Cockpit about the package. The pinger directory above is such a package. Its manifest.json file looks like this:

{
    "version": 0,
    "tools": {
        "pinger": {
            "label": "Pinger",
            "path": "ping.html"
        }
    }
}

The manifest above has a "tools" subsection, which means that it will appear in the lower section of the menu (see the manifest documentation for details). Each tool is listed in the menu by Cockpit. The "path" is the name of the HTML file that implements the tool, and the "label" is the text to show in the menu.

You’ll notice that we haven’t told Cockpit about how to find the package yet. To do so you either copy or symlink the package into one of two places:

~/.local/share/cockpit in your home directory. It’s used for user specific packages and ones that you’re developing. You can edit these on the fly and refresh your browser to see changes.
/usr/share/cockpit is the location for installed packages available to all users of a system. Changing files in this path requires administrator (“root”) privileges. These should not be changed while Cockpit is running.

Since we’re going to be actively editing this package, let’s symlink it into the first location, in your home directory.

mkdir -p ~/.local/share/cockpit
ln -snf $PWD ~/.local/share/cockpit/pinger

To list the Cockpit packages which are installed, use the following command:

$ cockpit-bridge --packages
...
pinger: /home/.../.local/share/cockpit/pinger
...

You should see pinger listed among all the active modules, like the above example.

Log into Cockpit on this machine with your current user name, as the package is installed in your home directory. (If you’re already logged in to Cockpit with your user account, you can simply reload your browser.)

You should now see a new item:

The pinger tool itself looks like this:

Lets take a look at the pinger HTML, and see how it works.

<!DOCTYPE html>
<html>
<head>
    <title>Pinger</title>
    <meta charset="utf-8">
    <script src="../base1/cockpit.js"></script>
</head>
<body>
    <main tabindex="-1">
        <section>
            <div>
                <div>
                    <label for="address">Address</label>
                    <input id="address" value="8.8.8.8">
                </div>
                <div>
                    <button id="ping">Ping</button>
                    <span id="result"></span>
                </div>
                <div>
                    <pre id="output"></pre>
                </div>
            </div>
        </section>
    </main>

    <script src="pinger.js"></script>
</body>
</html>

Included in the <head> block: cockpit.js is the basic API for interacting with the system, as well as Cockpit itself. You can find detailed documentation in the Cockpit guide.

The HTML is pretty basic. It defines a little form with a field to type an address, a button to click to start pinging, and an area to present output and results.

The logic lives in pinger.js, shown in full here:

const address = document.getElementById("address");
const output = document.getElementById("output");
const result = document.getElementById("result");
const button = document.getElementById("ping");

function ping_run() {
    cockpit.spawn(["ping", "-c", "4", address.value])
        .stream(ping_output)
        .then(ping_success)
        .catch(ping_fail);

    result.innerHTML = "";
    output.innerHTML = "";
}

function ping_success() {
    result.style.color = "green";
    result.innerHTML = "success";
}

function ping_fail() {
    result.style.color = "red";
    result.innerHTML = "fail";
}

function ping_output(data) {
    output.append(document.createTextNode(data));
}

// Connect the button to starting the "ping" process
button.addEventListener("click", ping_run);

// Send a 'init' message.  This tells integration tests that we are ready to go
cockpit.transport.wait(function() { });

First we get a bunch of variables pointing to the HTML elements we want to interact with. Next we attach a handler to the Ping button so that the ping_run() function is called when it is clicked.

function ping_run() {
}
...
button.addEventListener("click", ping_run);

The ping_run() function is where the magic happens. cockpit.spawn lets you spawn processes on the server and interact with them via stdin and stdout.

Here we spawn the ping command with some arguments:

cockpit.spawn(["ping", "-c", "4", address.val()])

In a web browser you cannot block and wait until a method call completes. Anything that doesn’t happen instantaneously gets its results reported back to you by means of callback handlers.

JavaScript has a standard interface called a Promise. You add handlers by calling the .then() or .catch() methods and registering callbacks (Note: historically these have been called .done() and .fail(), but these should not be used any more in new code.) The cockpit.spawn specific .stream() handler registers a callback to be invoked whenever the process produces output.

   <some promise>
   .stream(ping_output)
   .then(ping_success)
   .catch(ping_fail);
}

The ping_success() and ping_fail() and ping_output() update the display as you would expect.

Warning: Don’t start long-running, uninterruptible processes in this naïve way. Browser tabs are easily closed, network connections get severed, laptops suspend, and so on. Take care to use a mechanism like systemd-run (or similar) for processes that should not be interrupted, such as installation procedures.

This should be enough to get you started with your first useful (but admittedly basic) Cockpit page! Please see the Contributing page for more documentation on where to grow from here.

Make your Cockpit page easily installable

Mon, 09 Apr 2018 10:00:00 +0000

Since version 152, Cockpit can discover and install packages that add pages to Cockpit. We call them “Applications” and as of now, only two of them exist: We have Fleet Commander and Cockpit’s own Diagnostic Reports in Fedora. You might have seen them on the Applications page:

If you want your own page to appear there, you have to add suitable AppStream data to your package in the right location.

When your package is included in a distribution repository, the repository machinery will find the data in your package and make it available to software managers, such as the Cockpit “Applications” page.

For a Cockpit component, the AppStream data looks like this:

<component type="addon">
  <id>org.cockpit_project.demo-app</id>
  <metadata_license>CC0-1.0</metadata_license>
  <name>Demo Application</name>
  <summary>
    A demo add-on application for Cockpit
  </summary>
  <description>
    <p>This is a demo application</p>
  </description>
  <extends>org.cockpit_project.cockpit</extends>
  <launchable type="cockpit-manifest">demo-app</launchable>
</component>

This would be placed at /usr/share/metainfo/org.cockpit_project.demo-app.metainfo.xml in your package.

The important bit is the launchable element with type cockpit-manifest. Any such AppStream component will be offered for installation by Cockpit. The value is the name of the Cockpit package for your page.

Use the component type addon and add an extends element for org.cockpit_project.cockpit.

You should of course come up with your own value for the id element, in the usual reverse-DNS style, and adjust the filename accordingly.

Using Cockpit test VMs with your own test framework

Wed, 28 Mar 2018 00:00:00 +0000

The Cockpit Starter Kit provides the scaffolding for your own Cockpit extensions: a simple page (in React), build system (webpack, babel, eslint, etc.), and an integration test using Cockpit’s own Python test API on top of the Chromium DevTools Protocol. See the recent introduction for details.

But in some cases you want to use a different testing framework; perhaps you have an already existing project and tests. Then it is convenient and recommended to still using Cockpit’s test VM images: they provide an easy way to test your project on various Fedora/Red Hat/Debian/Ubuntu flavors; and they take quite a lot of effort to maintain! Quite fortunately, using the test images is not tightly bound to using Cockpit’s test API, and not even to tests being written Python. They can be built and used entirely through command line tools from Cockpit’s bots/ directory, so you can use those with any programming language and test framework.

Building and interacting with a test VM

To illustrate this, let’s check out the Starter Kit and build a CentOS 7 based VM with cockpit and the starter kit installed:

$ git clone https://github.com/cockpit-project/starter-kit.git
$ cd starter-kit
$ make vm

Ordinarily, the generated test/images/centos-7.qcow2 would be used by test/check-starter-kit. But let’s tinker around with the VM image manually. Cockpit’s testvm.py module for using these VMs can be used as a command line program:

$ bots/machine/testvm.py centos-7
ssh -o ControlPath=/tmp/ssh-%h-%p-%r-23253 -p 2201 root@127.0.0.2
http://127.0.0.2:9091
RUNNING

It takes a few seconds to boot the VM, then it prints three lines:

The SSH command to run something inside the VM
The URL for the forwarded Cockpit port 9090
A constant RUNNING flag that test suites can poll for to know when to proceed.

You can now open that URL in your browser to log into Cockpit (user “admin”, password “foobar”) and see the installed Starter Kit page, or run a command in the VM through the given SSH command:

$ ssh -o ControlPath=/tmp/ssh-%h-%p-%r-23253 -p 2202 root@127.0.0.2 head -n2 /etc/os-release
NAME="CentOS Linux"
VERSION="7 (Core)"

The VM gets shut down once the testvm.py process gets a SIGTERM (useful for test suites) or SIGINT (useful for just pressing Control-C when interactively starting this in a shell).

Using testvm.py in your test suite

Let’s use the above in a Puppeteer test. check-puppeteer.js is a straight port of check-starter-kit; of course it is a little longer than the original as we don’t have the convenience functions of testlib.py to automatically start and tear down VMs or do actions like “log into Cockpit”, but it is still fairly comprehensible. Download it into the tests/ directory of your starter-kit checkout, then install puppeteer:

$ PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=1 npm install puppeteer@0.12.0

This will avoid downloading an entire private copy of chromium-browser and use the system-installed one. (Of course you can also just call npm install puppeteer if you don’t care about the overhead). Now run the tests:

$ DEBUG="puppeteer:page,puppeteer:frame" PYTHONPATH=bots/machine test/check-puppeteer.js

This will run them in a verbose mode where you can follow the browser queries and events.

Let’s walk through some of the code:

function startVm() {
    return new Promise((resolve, reject) => {
        let proc = child_process.spawn("bots/machine/testvm.py", [testOS], { stdio: ["pipe", "pipe", "inherit"] });
        let buf = "";
        proc.stdout.on("data", data => {
            buf += data.toString();
            if (buf.indexOf("\nRUNNING\n") > 0) {
                let lines = buf.split("\n");
                resolve({ proc: proc, ssh: lines[0], cockpit: lines[1] });
            }
        });
        proc.on("error", err => { throw `Failed to start vm-run: ${err}` });
    });
}

This uses testvm.py as above to launch the VM. In a “real” test suite this would go into the per-test setup code. check-puppeteer.js does not use any test case organization framework (like jest or QUnit), but if you have more than two or three test cases it’s recommended to use one.

async function testStarterKit() {
    const vm = await startVm();

    const browser = await puppeteer.launch(
        // disable sandboxing to also work in docker
        { headless: true, executablePath: 'chromium-browser', args: [ "--no-sandbox" ] });

This is the actual test case. Here we start Puppeteer, and here you can change various options to influence the test. For example, set headless: false to get a visible Chomium window and follow live what the test does (or where it hangs).

    const page = await browser.newPage();

    try {
        // log in
        await page.goto(vm.cockpit);
        await page.type('#login-user-input', 'admin');
        await page.type('#login-password-input', 'foobar');
        await page.click('#login-button');

This is the equivalent of Cockpit test’s Browser.login_and_go(). In a real test you would probably factorize this into a helper function.

        await page.waitFor('#host-nav a[title="Starter Kit"]');
        await page.goto(vm.cockpit + "/starter-kit");
        let frame = getFrame(page, 'cockpit1:localhost/starter-kit');

        // verify expected heading
        await frame.waitFor('.container-fluid h2');
        await frame.waitForFunction(() => document.querySelector(".container-fluid h2").innerHTML == "Starter Kit");

        // verify expected host name
        let hostname = vmExecute(vm, "cat /etc/hostname").trim();
        await frame.waitFor('.container-fluid span');
        await frame.waitForFunction(
            h => document.querySelector(".container-fluid span").innerHTML == ("Running on " + h),
            {}, hostname);
    }

This is a direct translation of what check-starter-kit does: Assert the expected heading and host name message.

    catch (err) {
        const attachments = process.env["TEST_ATTACHMENTS"];
        if (attachments) {
            console.error("Test failed, taking screenshot...");
            await page.screenshot({ path: attachments + "/testStarterKit-FAIL.png"});
        }
        throw err;
    }

This part is optional, but very useful for debugging failed tests. If any assertion fails, this creates a PNG screenshot from the current browser page state. Run the test with TEST_ATTACHMENTS=/some/existing/directory to enable this. The Cockpit CI machinery will export any files in this directory to the http browsable test results directory.

     finally {
        await browser.close();
        vm.proc.kill();
    }
};

This is a poor man’s “test teardown” which closes the browser and VM.

Feedback

starter-kit and external Cockpit project tests are still fairly new, so there are for sure things that could work more robustly, easier, more flexibly, or just have better documentation. If you run into trouble, please don’t hesitate telling us about it, preferably by filing an issue.

Happy hacking!

The Cockpit Development Team

Starter Kit - the turn-key template for your own pages

Fri, 09 Mar 2018 00:00:00 +0000

The bare minimum

Cockpit’s API makes it easy to create your own pages (or “extensions” if you will) that appear in Cockpit’s menu and interact with your system in any way you like. Our pet example is the Pinger which is just the bare minimum: a HTML file with a form to enter an IP, a small piece of JavaScript to call the ping Linux command through Cockpit spawn() and capture its output; and a manifest file which tells cockpit how to add it to the menu and where the entry point is.

There is a rather old blog post which explains the Pinger example in detail. Cockpit changed its visual design quite dramatically since then, Pinger’s JavaScript got split into a separate file and does not use jQuery any more, but aside from these details that post is still generally applicable.

Requirements for real projects

Pinger is great for explaining and understanding the gist of how Cockpit works. But an actual production-ready project requires a lot more:

Separation of HTML, CSS, and JavaScript code: This ensures that your code can use a safe Content-Security-Policy and does not have to use e. g. unsafe-inline. We strongly recommend this for third-party pages, and absolutely require this for Cockpit’s own pages.
Modern frameworks for creating page contents. For any non-trivial page you really don’t want to dabble with piecing together myelement.innerHTML = … strings, but use something like React to build page contents and PatternFly so that your page fits into Cockpit’s design.
Use Babel to write your code in modern ES6 JavaScript.
Use ESLint to spot functional and legibility errors in your code.
A build system like webpack to drive all of the above and build blobs (“minified Javascript in a single file”) that are efficiently consumable by browsers.
Building of release tarballs, source and binary RPMs for testing and distribution.
Tests to make sure your code keeps working, new features work on all supported operating systems, and changes (pull requests) get validated.
As a bonus, easy and safe testing of your page in a Vagrant virtual machine.

Sounds complex? It indeed is for someone who is not familiar with the ever-changing “modern” JavaScript world, and doesn’t want to learn the details of all of these before you can even begin working on your code. This is where the Starter Kit comes in!

Bootstrapping your way from zero to “works!”

The Cockpit Starter Kit is an example project which provides all of the above requirements. It provides a simple React page that uses the cockpit.file() API to read /etc/hostname and show it. There is also an accompanying test that verifies this page. The other files are mostly build system boilerplate, i. e. the things you don’t want to worry about as the first thing when you start a project.

So, how to get this? Make sure you have the npm package installed. Then check out the repository and build it:

git clone https://github.com/cockpit-project/starter-kit.git
cd starter-kit
make

After that, install (or rather, symlink) the webpack-generated output page in dist/ to where cockpit can see it:

mkdir -p ~/.local/share/cockpit
ln -s `pwd`/dist ~/.local/share/cockpit/starter-kit

Now you should be able to log into https://localhost:9090 and see the “Starter Kit” menu entry:

The symlink into your source code checkout is a very convenient and efficient way of development as you can just type make after changing code and directly see the effect in Cockpit after a page reload.

You should now play around with this a little by hacking src/starter-kit.jsx, running make, and reloading the page. For example, try to read and show another file, run a program and show its output, or use cockpit.file(“/etc/hostname”).watch(callback) to react to changes of /etc/hostname and immediately update the page.

Testing

Untested code is broken code. If not here and now, then in the future or some other operating system. This is why Cockpit has a rather complex machinery of regularly building 26 (!) VM images ranging from RHEL-7 and Fedora 27 over various releases of Debian and Ubuntu to OpenShift and Windows 8, and running hundreds of integration tests on each of them for every PR in an OpenShift cluster.

Replicating this for other projects isn’t easy, and this has been one, if not the major reason why there aren’t many third-party Cockpit projects yet. So we now made it possible for third-party GitHub projects to use Cockpit’s CI environment, test VM images, and (independently) Cockpit’s browser test abstraction API.

starter-kit uses all three of those: When you run make check, it will:

build an RPM out of your current code
check out cockpit’s bots/ directory that has the current image symlinks and tools to download, customize and run VM images
check out cockpit’s tests/common directory from a stable Cockpit release (as the API is not guaranteed to be stable) which provides a convenient Python API for the Chrome DevTools protocol
download Cockpit’s current CentOS-7 VM image; you can test on a different operating system by setting the environment variable TEST_OS=fedora-27 (or a different operating system - but note that starter-kit does not currently build debs)
create an overlay on that pristine centos-7 image with the operating system’s standard “cockpit” package and your locally built starter-kit RPM installed
run a VM with that overlay image with libvirt and QEMU
launch a chromium (or chromium-headless) browser
Run the actual check-starter-kit test which instructs the web browser what to do and which assertions to make

[starter-kit] $ make check
[...]
rpmbuild -bb [...] cockpit-starter-kit.spec
[...]
git fetch --depth=1 https://github.com/cockpit-project/cockpit.git
From https://github.com/cockpit-project/cockpit
 * branch            HEAD       -> FETCH_HEAD
git checkout --force FETCH_HEAD -- bots/
[...]
bots/image-customize -v -r 'rpm -e cockpit-starter-kit || true' -i cockpit -i `pwd`/cockpit-starter-kit-*.noarch.rpm -s /home/martin/upstream/starter-kit/test/vm.install centos-7
[...]
TEST_AUDIT_NO_SELINUX=1 test/check-starter-kit
1..1
# ----------------------------------------------------------------------
# testBasic (__main__.TestStarterKit)
#

ok 1 testBasic (__main__.TestStarterKit) # duration: 21s
# TESTS PASSED [22s on donald]

Note that the first time you run this will take a long time due to the rather large VM image download. But it will be reused for further tests.

For writing your own tests with the Cockpit Python API, have a look at the Browser and MachineCase classes in testlib.py. These provide both low-level (like click() or key_press()) and high-level (like login_and_go()) methods for writing test cases. And of course you have a wealth of Cockpit tests for getting inspiration.

starter-kit itself is also covered by Cockpit’s CI, i. e. pull requests will run tests on CentOS 7 and Fedora 27 (example, click on “View Details”). Please come and talk to us once your project is mature enough to do the same, then we can enable automatic pull request testing on your project as well.

Using different technologies

starter-kit makes opinionated choices like using React, webpack, and Cockpit’s testing framework. These are the technologies that we use for developing Cockpit itself, so if you use them you have the best chance that the Cockpit team can help you with problems. Of course you are free to replace any of these, especially if you have already existing code/tests or a build system.

For example, it is straightforward to just use Cockpit’s test images with the image-customize tool and running these as ephemeral VMs with testvm.py, but not use Cockpit’s test/common. Tests can also be written with e. g. puppeteer or nightmare. I will write about that separately.

Feedback

starter-kit is still fairly new, so there are for sure things that could work more robustly, easier, more flexibly, or just have better documentation. If you run into trouble, please don’t hesitate telling us about it, preferably by filing an issue.

Happy hacking!

The Cockpit Development Team

Using Vagrant to Develop Cockpit

Thu, 08 Oct 2015 00:00:00 +0000

Starting with Cockpit release 0.79 you can use Vagrant to bring up a VM in which you can test or develop Cockpit. The VM is isolated from your main system so any system configuration you change via Cockpit will only happen in the VM.

The Vagrant VM mounts the Cockpit package assets from your git repository checkout, so when you make on the host system, you can refresh the browser and immediately see the resulting changes. For changes to C code, the Cockpit binaries would have to be rebuilt and testing via Vagrant won’t work.

Getting Started

To start, you’ll need Vagrant. On Fedora I use vagrant-libvirt. In addition keep in mind that on vagrant-libvirt requires root privileges, so you’ll need to use vagrant with sudo.

$ sudo yum install vagrant vagrant-libvirt

Next, in a copy of the Cockpit git repository, you run vagrant up:

$ git clone https://github.com/cockpit-project/cockpit
$ cd cockpit
$ sudo vagrant up

The first time this runs it’ll take a while, but eventually you’ll have a Vagrant VM running. When you do this step again, it should be pretty fast.

The VM will listen for connections on your local machine’s http://localhost:9090, but even though you’re connecting to localhost it’ll be Cockpit in the VM you’re talking to.

If you already have Cockpit running on your local machine, then this won’t work, and you’ll need to use the IP address of the VM instead of localhost. To find it:

$ sudo vagrant ssh-config

Two user accounts are created in the VM, and you can use either one to log into Cockpit:

User: “admin” Password: “foobar”
User: “root” Password: “foobar”

Testing a Pull Request

If there’s a Cockpit pull request that you’d like to test, you can now do that with the Vagrant VM. Replace the 0000 in the following command with the number of the pull request:

$ git fetch origin pull/0000/head
$ git checkout FETCH_HEAD

The pull request can only contain code to Cockpit package assets. If it contains changes to the src/ directory, then the pull request involves rebuilding binaries, and testing it via Vagrant won’t work.

Now refresh your browser, or if necessary, login again. You should see the changes in the pull request reflected in Cockpit.

Making a change

You can make a change to Cockpit while testing that out in your Vagrant VM. The changes should be to Cockpit package assets. If you change something in the src/ directory, then binaries will have to be rebuilt, and testing it via Vagrant won’t work.

I chose change some wording in the sidebar in pkg/shell/index.html:

          <a data-toggle="collapse" data-target="#tools-panel" class="collapsed" translatable="yes">
-           Tools
+           Beavers 'n Ducks
          </a>

And after refreshing Cockpit, I can see that change:

The same applies to javascript or CSS changes as well. In order to actually contribute a change to Cockpit you’ll want to look at the information about Contributing and if you need help understanding how to add a plugin package you can look at the Developer Guide.

Bringing the Vagrant VM in sync

After each Cockpit release, there will be new binary parts to Cockpit. In order to continue to use the Vagrant VM, you’ll need to rebuild it. A message like this should appear when that’s necessary.

Rebuild the Vagrant VM like this:

$ sudo vagrant destroy
$ sudo vagrant up

Troubleshooting

On Fedora, FirewallD got in the way of Vagrants use of NFS. On my machine, I had to do this to get it to work:

```text $ sudo firewall-cmd –set-default-zone=trusted

Making REST calls from Javascript in Cockpit

Fri, 10 Jul 2015 00:00:00 +0000

Note: This post has been updated for changes in Cockpit 0.90 and later.

Cockpit is a user interface for servers. In earlier tutorials there’s a guide on how to add components to Cockpit.

Not all of the system APIs use DBus. So sometimes we find ourselves in a situation where we have to use REST (which is often just treated as another word for HTTP) to talk to certain parts of the system. For example Docker has a REST API.

For this tutorial you’ll need at least Cockpit 0.58. There was one last tweak that helped with the superuser option you see below. You can install it in Fedora 22 or build it from git.

Here we’ll make a package called docker-info which shows info about the docker daemon. We use the /info docker API to retrieve that info.

I’ve prepared the docker-info package here. It’s just two files. To download them and extract to your current directory, and installs it as a Cockpit package:

$ wget https://cockpit-project.org/files/docker-info.tgz -O - | tar -xzf -
$ cd docker-info/
$ mkdir -p ~/.local/share/cockpit
$ ln -snf $PWD ~/.local/share/cockpit/

Previously we talked about how packages are installed, and what manifest.json does so I won’t repeat myself here. But to make sure the above worked correctly, you can run the following command. You should see docker-info listed in the output:

$ cockpit-bridge --packages
...
docker-info: .../.local/share/cockpit/docker-info
...

If you’re logged into Cockpit on this machine, first log out. And log in again. Make sure to log into Cockpit with your current user name, since you installed the package in your home directory. You should now see a new item in the Tools menu called Docker Info:

After a moment, you should see numbers pop up with some stats about the docker daemon. Now in a terminal try to run something like:

$ sudo docker run -ti fedora /bin/bash

You should see the numbers update as the container is pulled and started. When you type exit in the container, you should see the numbers update again. How is this happening? Lets take a look at the docker-info HTML:

<head>
    <title>Docker Info</title>
    <meta charset="utf-8">
    <link href="../base1/cockpit.css" type="text/css" rel="stylesheet">
    <script src="../base1/jquery.js"></script>
    <script src="../base1/cockpit.js"></script>
</head>
<body>
    <div class="container-fluid">
        <h2>Docker Daemon Info</h2>
        <ul>
            <li>Total Memory: <span id="docker-memory">?</span></li>
            <li>Go Routines: <span id="docker-routines">?</span></li>
            <li>File Descriptors: <span id="docker-files">?</span></li>
            <li>Containers: <span id="docker-containers">?</span></li>
            <li>Images: <span id="docker-images">?</span></li>
        </ul>
    </div>

    <script>
        var docker = cockpit.http("/var/run/docker.sock", { superuser: "try" });

        function retrieve_info() {
            var info = docker.get("/info");
            info.done(process_info);
            info.fail(print_failure);
        }

        function process_info(data) {
            var resp = JSON.parse(data);
            $("#docker-memory").text(resp.MemTotal);
            $("#docker-routines").text(resp.NGoroutines);
            $("#docker-files").text(resp.NFd);
            $("#docker-containers").text(resp.Containers);
            $("#docker-images").text(resp.Images);
        }

        /* First time */
        retrieve_info();

        var events = docker.get("/events");
        events.stream(got_event);
        events.always(print_failure);

        function got_event() {
            retrieve_info();
        }

        function print_failure(ex) {
            console.log(ex);
        }
    </script>
</body>
</html>

First we include jquery.js and cockpit.js. cockpit.js defines the basic API for interacting with the system, as well as Cockpit itself. You can find detailed documentation here.

<script src="../base1/jquery.js"></script>
<script src="../base1/cockpit.js"></script>

We also include the cockpit.css file to make sure the look of our tool matches that of Cockpit. The HTML is pretty basic, defining a little list where the info shown.

In the javascript code, first we setup an HTTP client to access docker. Docker listens for HTTP requests on a Unix socket called /var/run/docker.sock. In addition the permissions on that socket often require escalated privileges to access, so we tell Cockpit to try to gain superuser privileges for this task, but continue anyway if it cannot:

var docker = cockpit.http("/var/run/docker.sock", { superuser: "try" });

First we define how to retrieve info from Docker. We use the REST /info API to do this.

function retrieve_info() {
    var info = docker.get("/info");
    info.done(process_info);
    info.fail(print_failure);
}

In a browser you cannot stop and wait until a REST call completes. Anything that doesn’t happen instantaneously gets its results reported back to you by means of callback handlers. jQuery has a standard interface called a promise. You add handlers by calling the .done() or .fail() methods and registering callbacks.

The result of the /info call is JSON, and we process it here. This is standard jQuery for filling in text data into the various elements:

function process_info(data) {
    var resp = JSON.parse(data);
    $("#docker-memory").text(resp.MemTotal);
    $("#docker-routines").text(resp.NGoroutines);
    $("#docker-files").text(resp.NFd);
    $("#docker-containers").text(resp.Containers);
    $("#docker-images").text(resp.Images);
}

And then we trigger the invocation of our /info REST API call.

/* First time */
retrieve_info();

Because we want to react to changes in Docker state, we also start a long request to its /events API.

var events = docker.get("/events");

The .get("/events") call returns a jQuery Promise. When a line of event data arrives, the .stream() callback in invoked, and we use it to trigger a reload of the Docker info.

events.stream(got_event);
events.always(print_failure);

function got_event() {
    retrieve_info();
}

This is a simple example, but I hope it helps you get started. There are further REST javascript calls. Obviously you can also do POST and so on.

Protocol for Web access to System APIs

Tue, 16 Dec 2014 00:00:00 +0000

Note: This post has been updated for changes in Cockpit 0.48 and later.

A Linux system today has a lot of local system configuration APIs. I’m not talking about library APIs here, but things like DBus services, command/scripts to be executed, or files placed in various locations. All of these constitute the API by which we configure a Linux system. In Cockpit we access these APIs from a web browser (after authentication of course).

How do we access the system APIs? The answer is the cockpit-bridge tool. It proxies requests from the Cockpit user interface, running in a web browser, to the system. Typically the cockpit-bridge runs as the logged in user, in a user session. It has similar permissions and capabilities as if you had used ssh to log into the system.

Lets look at an example DBus API that we call from Cockpit. systemd has an API to set the system host name, called SetStaticHostname. In Cockpit we can invoke that API using simple JSON like this:

{
  "call": [
    "/org/freedesktop/hostname1",
    "org.freedesktop.hostname1",
    "SetStaticHostname", [ "mypinkpony.local", true ]
  ]
}

The protocol that the web browser uses is a message based protocol, and runs over a WebSocket. This is a “post-HTTP” protocol, and isn’t limited by the request/response semantics inherent to HTTP. Our protocol has a lot of JSON, and has a number of interesting characteristics, which you’ll see below. In general we’ve tried to keep this protocol readable and debuggable.

The cockpit-bridge tool speaks this protocol on its standard in and standard output. The cockpit-ws process hosts the WebSocket and passes the messages to cockpit-bridge for processing.

Following along: In order to follow along with the stuff below, you’ll need at least Cockpit 0.48. The protocol is not yet frozen, and we merged some cleanup recently. You can install it on Fedora 21 using a COPR or build it from git.

Channels

Cockpit can be doing lots of things at the same time and we don’t want to have to open a new WebSocket each time. So we allow the protocol to be shared by multiple concurrent tasks. Each of these is assigned a channel. Channels have a string identifier. The data transferred in a channel is called the payload. To combine these into a message I simply concatenate the identifier, a new line, and the payload. Lets say I wanted to send the message Oh marmalade! over the channel called scruffy the message would look like this:

scruffy
Oh marmalade!

How do we know what channel to send messages on? We send control messages on a control channel to open other channels, and indicate what they should do. The identifier for the control channel is an empty string. More on that below.

Framing

In order to pass a message based protocol over a plain stream, such the standard in and standard out of cockpit-bridge, one needs some form of framing. This framing is not used when the messages are passed over a WebSocket, since WebSockets inherently have a message concept.

The framing the cockpit-bridge uses is simply the byte length of the message, encoded as a string, and followed by a new line. So Scruffy’s 21 byte message above, when sent over a stream, would like this:

21
scruffy
Oh marmalade!

Alternatively, when debugging or testing cockpit-bridge you can run in an interactive mode, where we frame our messages by using boundaries. That way we don’t have to count the byte length of all of our messages meticulously, if we’re writing them by hand. We specify the boundary when invoking cockpit-bridge like so:

$ cockpit-bridge --interact=----

And then we can send a message by using the ---- boundary on a line by itself:

scruffy
Oh marmalade!
----

Control channels

Before we can use a channel, we need to tell cockpit-bridge about the channel and what that channel is meant to do. We do this with a control message sent on the control channel. The control channel is a channel with an empty string as an identifier. Each control message is a JSON object, or dict. Each control message has a "command" field, which determines what kind of control message it is.

The "open" control message opens a new channel. The "payload" field indicates the type of the channel, so that cockpit-bridge knows what to do with the messages. The various channel types are documented. Some channels connect talk to a DBus service, others spawn a process, etc.

When you send an "open" you also choose a new channel identifier and place it in the "channel" field. This channel identifier must not already be in use.

The "echo" channel type just sends the messages you send to the cockpit-bridge back to you. Here’s the control message that is used to open an echo channel. Note the empty channel identifier on the first line:


{
  "command": "open",
  "channel": "mychannel",
  "payload": "echo"
}

Now we’re ready to play … Well almost.

The very first control message sent to and from cockpit-bridge should be an "init" message containing a version number. That version number is 1 for the foreseeable future.


{
  "command": "init",
  "version": 1
}

Try it out

So combining our knowledge so far, we can run the following:

$ cockpit-bridge --interact=----

In this debugging mode sent by cockpit-bridge will be bold in your terminal. Now paste the following in:


{ "command": "open", "channel": "mychannel", "payload": "echo" }
----
mychannel
This is a test
----

You’ll notice that cockpit-bridge sends your message back. You can use this technique to experiment. Unfortunately cockpit-bridge exits immediately when it’s stdin closes, so you can’t yet use shell redirection from a file effectively.

Making a DBus method call

To make a DBus method call, we open a channel with the payload type "dbus-json3". Then we send JSON messages as payloads inside that channel. An additional field in the "open" control message is required. The "name" field is the bus name of the DBus service we want to talk to:


{
  "command": "open",
  "channel": "mydbus",
  "payload": "dbus-json3",
  "name": "org.freedesktop.hostname1"
}

Once the channel is open we send a JSON object as a payload in the channel with a "call" field. It is set to an array with the DBus interface, DBus object path, method name, and an array of arguments.

mydbus
{
  "call": [ "/org/freedesktop/hostname1", "org.freedesktop.hostname1",
```unknown
        "SetStaticHostname", [ "mypinkpony.local", true ] ],
  "id": "cookie"
}

If we want a reply from the service we specify an `"id"` field. The resulting `"reply"` will have a matching `"id"` and would look something like this:

<pre>
mydbus
{
  "reply": [ null ],
  "id": "cookie"
}
</pre>

If an error occurred you would see a reply like this:

<pre>
mydbus
{
  "error": [
```unknown
"org.freedesktop.DBus.Error.UnknownMethod",
[ "MyMethodName not available"]
  ],
  "id":"cookie"
}
</pre>

This is just the basics. You can do much more than this with DBus, including watching for signals, lookup up properties, tracking when they change, introspecting services, watching for new objects to show up, and so on.

Spawning a process

Spawning a process is easier than calling a DBus method. You open the channel with the payload type "stream" and you specify the process you would like to spawn in the "open" control message:


{
  "command": "open",
  "channel": "myproc",
  "payload": "stream",
  "spawn": [ "ip", "addr", "show" ]
}

The process will send its output in the payload of one or more messages of the "myproc" channel, and at the end you’ll encounter the "close" control message. We haven’t looked at until now. A "close" control message is sent when a channel closes. Either the cockpit-bridge or its caller can send this message to close a channel. Often the "close" message contains additional information, such as a problem encountered, or in this case the exit status of the process:


{
  "command": "close",
  "channel": "myproc",
  "exit-status": 0
}

Doing it over a WebSocket

Obviously in Cockpit we send all of these messages from the browser through a WebSocket hosted by cockpit-ws. cockpit-ws then passes them on to cockpit-bridge. You can communicate this way too, if you configure Cockpit to accept different Websocket Origins.

And on it goes

There are payload types for reading files, replacing them, connecting to unix sockets, accessing system resource metrics, doing local HTTP requests, and more. Once the protocol is stable, solid documentation is in order.

I hope that this has given some insight into how Cockpit works under the hood. If you’re interested in using this same protocol, I’d love to get feedback … especially while the basics of the protocol are not yet frozen.

Using DBus from Javascript in Cockpit

Thu, 13 Nov 2014 00:00:00 +0000

Note: This post has been updated for changes in Cockpit 0.90 and later.

Cockpit is a user interface for servers. As we covered in the last tutorial you can add user interface component to Cockpit, and build your own parts of the Server UI.

Much of Cockpit interacts with the server using DBus. We have a powerful yet simple API for doing that, and you should use DBus too when building your own Cockpit user interfaces. For this tutorial you’ll need at least Cockpit 0.41. A few tweaks landed in that release to solve a couple rough edges we had in our DBus support. You can install it in Fedora 21 or build it from git.

Here we’ll make a package called zoner which lets you set the time zone of your server. We use the systemd timedated DBus API to do actually switch time zones.

I’ve prepared the zoner package here. It’s just two files. To download them and extract to your current directory, and installs it as a Cockpit package:

$ wget https://cockpit-project.org/files/zoner.tgz -O - | tar -xzf -
$ cd zoner/
$ mkdir -p ~/.local/share/cockpit
$ ln -snf $PWD ~/.local/share/cockpit/zoner

$ cockpit-bridge --packages
...
zoner: .../.local/share/cockpit/zoner
...

Try it out by typing Australia/Tasmania in the box, and clicking Change. You should see that the Time Zone changes. You can verify this by typing the following on the same server in a terminal:

$ date
Sa 15. Nov 01:48:01 AEDT 2014

Try typing an invalid timezone like blah, and you’ll see an error message displayed. Now try changing the timezone from the terminal using the timedatectl command while you have Cockpit open displaying your Time Zone screen:

$ sudo timedatectl set-timezone UTC

You should see your timezone on your screen update immediately to reflect the new state of the server. So how does this work? Lets take a look at the zoner HTML:

<head>
    <title>Time Zone</title>
    <meta charset="utf-8">
    <link href="../base1/cockpit.css" type="text/css" rel="stylesheet">
    <script src="../base1/jquery.js"></script>
    <script src="../base1/cockpit.js"></script>
</head>
<body>
    <div class="container-fluid" style='max-width: 400px'>
        <table class="cockpit-form-table">
            <tr>
                <td>Time Zone</td>
                <td><span id="current"></span></td>
            </tr>
            <tr>
                <td>New Zone</td>
                <td><input class="form-control" id="new" value="UTC"></td>
            </tr>
            <tr>
                <td><button class="btn btn-default btn-primary" id="change">Change</button></td>
                <td><span id="failure"></span></td>
            </tr>
        </table>
    </div>

    <script>
        var input = $("#new");
        var current = $("#current");
        var failure = $("#failure");

        $("#change").on("click", change_zone);

        var service = cockpit.dbus('org.freedesktop.timedate1');
        var timedate = service.proxy();
        $(timedate).on("changed", display_zone);

        function display_zone() {
            current.text(timedate.Timezone);
        }

        function change_zone() {
            var call = timedate.SetTimezone(input.val(), true);
            call.fail(change_fail);
            failure.empty();
        }

        function change_fail(err) {
            failure.text(err.message);
        }

    </script>
</body>
</html>

First we include jquery.js and cockpit.js. cockpit.js defines the basic API for interacting with the system, as well as Cockpit itself. You can find detailed documentation here.

<script src="../base1/jquery.js"></script>
<script src="../base1/cockpit.js"></script>

We also include the cockpit.css file to make sure the look of our tool matches that of Cockpit. The HTML is pretty basic, defining a little form where the current timezone is shown, a field to type an address, a button to click change to a new one, and an area to show errors.

In the javascript code, first we get a bunch of variables pointing to the HTML elements we want to interact with. Next we attach a handler to the Change button so that the change_zone() function is called when it is clicked.

$("#change").on("click", change_zone);

Next we connect to the timedated DBus service using the cockpit.dbus() function:

var service = cockpit.dbus('org.freedesktop.timedate1');

Now we make a proxy which represents a particular DBus interface containing methods and properties. Simple services have only one interface. When more than one interface or instance of that interface is present, there are additional arguments to the .proxy() method that you can specify.

var timedate = service.proxy();

Each interface proxy has a "changed" event we can connect to. When properties on the proxy change, or are received for the first time, this event is fired. We use this to call our display_zone() function and update the display of the current time zone:

$(timedate).on("changed", display_zone);

`Timezone` is a property on the [timedated DBus interface](http://www.freedesktop.org/wiki/Software/systemd/timedated/). We can access these properties directly, and the proxy will keep them up to date. Here we use the property to update our display of the current time zone:

function display_zone() {
    current.text(timedate.Timezone);
}

`SetTimezone` is a method on the [timedated DBus interface](http://www.freedesktop.org/wiki/Software/systemd/timedated/) interface, and we can invoke it directly as we would a javascript function. In this case we pass the arguments the DBus method expects, a `timezone` string, and a `user_interaction` boolean.

function change_zone() {
    var call = timedate.SetTimezone(input.val(), true);

In a web browser you cannot block and wait until a method call completes. Anything that doesn’t happen instantaneously gets its results reported back to you by means of callback handlers. jQuery has a standard interface called a promise. You add handlers by calling the .done() or .fail() methods and registering callbacks.

    call.fail(change_fail);
    failure.empty();
}

The change_fail() displays any failures that happen. In this case, SetTimezone DBus method has no return value, however if there were, we could use something like call.done(myhandler) to register a handler to receive them.

Notice that we relied on DBus to tell us when things changed and just updated the display from our event handler. That way we reacted both when the time zone changed due to an action in Cockpit, as well as an action on the server.

Again this is a simple example, but I hope it will whet your appetite to what Cockpit can do with DBus. Obviously you can also do signal handling, working with return values from methods, tracking all instances of a given interface, and other stuff you would expect to do as a DBus client.