Cockpit documentation

cockpit - Cockpit

Cockpit is a web accessible interactive admin interface for Linux machines. Cockpit can usually be accessed on port 9090 of the machine it’s installed on. Cockpit starts on demand. Use your system credentials to log in.

The cockpit-ws web service listens on port 9090 and is started on demand by systemd. The Cockpit web service authenticates the user, loads Cockpit into the browser, and starts cockpit-bridge in a Linux user session.

The cockpit-bridge provides Cockpit in the web browser with access to the system APIs. It does this over its standard in and standard out. The bridge is started like a shell once per Linux user session.

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Cockpit has been written by many contributors.

cockpit-tls(8) , cockpit.bridge(1) , systemd(1), Cockpit guide

cockpit.conf - Cockpit configuration file

Cockpit can be configured via /etc/cockpit/cockpit.conf. If $XDG_CONFIG_DIRS is set, then the first path containing a ../cockpit/cockpit.conf is used instead. Other configuration files and directories are searched for in the same way.

This file is not required and may need to be created manually. The file has a INI file syntax and thus contains key / value pairs, grouped into topical groups. See the examples below for details.

Note: The port that cockpit listens on cannot be changed in this file. To change the port change the systemd cockpit.socket file.

Cockpit can be configured to support the implicit grant OAuth authorization flow. When successful the resulting oauth token will be passed to cockpit-ws using the Bearer auth-scheme. For a login to be successful, cockpit will also need a to be configured to verify and allow Bearer tokens.

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Cockpit has been written by many contributors.

cockpit-ws(8), cockpit-tls(8)

cockpit-ws - Cockpit web service

cockpit-ws [--help] [--port PORT] [--address ADDRESS] [--no-tls] [--for-tls-proxy] [--local-ssh] [--local-session BRIDGE]

The cockpit-ws program is the web service component used for communication between the browser application and various configuration tools and services like cockpit-bridge(1).

Users or administrators should never need to start this program as it automatically started by systemd(1) on bootup, through cockpit-tls(8).

cockpit-ws is normally run behind the cockpit-tls TLS terminating proxy, and only deals with unencrypted HTTP by itself. But for backwards compatibility it can also handle TLS connections by itself when being run directly. For details how to configure certificates, please refer to the cockpit-tls(8) documentation.

When started via systemd(1) then cockpit-ws will exit after 90 seconds if nobody logs in, or after the last user is disconnected.

The cockpit-ws process will use the XDG_CONFIG_DIRS environment variable from the XDG basedir spec to find its cockpit.conf(5) configuration file.

In addition the XDG_DATA_DIRS environment variable from the XDG basedir spec can be used to override the location to serve static files from. These are the files that are served to a non-logged in user.

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Cockpit has been written by many contributors.

cockpit-tls(8) , cockpit.conf(5) , systemd(1)

cockpit-tls - TLS proxy for Cockpit web service

cockpit-tls [--help] [--port PORT] [--no-tls] [--idle-timeout SECONDS]

The cockpit-tls program is a TLS terminating HTTP proxy for cockpit-ws(8). It manages a set of isolated cockpit-ws instances, one per TLS client certificate, plus one for TLS without a client certificate, and one for unencrypted HTTP. With that, one session cannot tamper with another one through possible security vulnerability exploits.

Users or administrators should never need to start this program as it automatically started by systemd(1) via socket activation.

To specify the TLS certificate the web service should use, simply drop a file with the extension .cert in the /etc/cockpit/ws-certs.d directory, or below $XDG_CONFIG_DIRS if set (see cockpit.conf). If there are multiple files in this directory, then the highest priority one is chosen after sorting.

The .cert file should contain at least two OpenSSL style PEM blocks. First one or more BEGIN CERTIFICATE blocks for the server certificate and intermediate certificate authorities and a second one containing a BEGIN PRIVATE KEY or similar. The key must not be encrypted.

If there is no TLS certificate, a self-signed certificate is automatically generated using sscg (if available) or openssl and stored in the 0-self-signed.cert file.

When enrolling into a FreeIPA domain, an SSL certificate is requested from the IPA server and stored in 10-ipa.cert.

To check which certificate cockpit-ws will use, run the following command.

Or, on Debian-based systems:

If using certmonger to manage certificates, following command can be used to generate a certificate/key pair:

The cockpit-tls program expects the RUNTIME_DIRECTORY environment variable to be set to an empty directory (preferably in /run/) that is only accessible by the system user under which it is running. This contains the Unix sockets for communicating with the cockpit-ws instances, and in the future, state information about client certificates. This variable is normally set by the cockpit.service systemd unit.

In addition, cockpit-tls will use the XDG_CONFIG_DIRS environment variable from the XDG basedir spec to find its certificates and the cockpit.conf(5) configuration file.

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Cockpit has been written by many contributors.

cockpit-ws(8) , cockpit.conf(5) , systemd(1)

cockpit-desktop - Cockpit Desktop integration

cockpit-desktop URLPATH [SSH_HOST]

The cockpit-desktop program provides secure access to Cockpit pages in an already running desktop session. It starts a web server (cockpit-ws) and a web browser in an isolated network namespace, and a cockpit-bridge(8) in the running user session.

This avoids having to log into Cockpit, and having to enable cockpit.socket system-wide. The network isolation ensures that no other user, and not even other processes in the user’s session, can access this local web server.

URLPATH is the Cockpit page to open, i. e. the path component of Cockpit URLs. It is highly recommended to only open a particular page frame, not the entire Cockpit navigation and menu. For example, the path /cockpit/@localhost/storage/index.html will open the Storage page. It is also possible to give abbreviated forms of urls, such as “/storage” or “/network/firewall”.

SSH_HOST is an optional SSH remote host specification (hostname or username@hostname). If given, cockpit-bridge will be started on the remote host through ssh(1) instead, i. e. the Cockpit web browser will show that remote host. Note that this is more of an experimental/demo feature.

The BROWSER environment variable specifies the browser command (and possibly options) that will be used to open the requested Cockpit page. If not set, cockpit-desktop attempts to use an internal minimalistic WebKit browser, and failing that, will attempt to detect some reasonable alternatives.

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Cockpit has been written by many contributors.

cockpit-ws(8), cockpit-bridge(1)

cockpit-bridge - Cockpit Host Bridge

cockpit-bridge [--help] [--packages]

The cockpit-bridge program is used by Cockpit to relay messages and commands from the Web front end to the server. Among other things it relays DBus, and spawns processes on behalf of the Web user interface.

This program is not routinely run by users or administrators. It is in the $PATH so that Cockpit can find it when connecting between hosts. However there are some diagnostics available when running from the command line.

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Cockpit has been written by many contributors.

cockpit-ws(8)

pam_ssh_add - PAM module to auto load ssh keys into an agent

pam_ssh_add provides authentication and session modules that allow users to start their session with a running ssh-agent with as many ssh keys loaded as possible.

If used, the authentication module simply stores the authentication token for later use by the session module. Because this module performs no actual authentication it returns PAM_CRED_INSUFFICIENT on success and should always be accompanied by an actual authentication module in your pam configuration.

By default the session module will start a new ssh-agent and run ssh-add, loading any keys that exist in the default path for the newly logged in user. If any keys prompt for a password, and a authentication token was successfully stored, that token will be provided as the password.

Please send bug reports to either the distribution bug tracker or the upstream bug tracker.

Cockpit has been written by many contributors.

The target server will need to have password based authentication enabled in sshd.

The target server will need to be a member of the same domain as the primary server and your domain must be whitelisted in your browser. See the SSO documentation for how to set this up.

When you successfully log into the primary server, a ssh-agent is started and keys are loaded into it by running ssh-add without any arguments. Any passphrase prompt is answered with the password used to log into the primary server.

Cockpit provides a user interface for loading other keys into the agent that could not be automatically loaded.

The target server will need to have public key authentication enabled in sshd, and the public key you wish to use must be present in ~/.ssh/authorized_keys. Cockpit has a user interface for creating SSH keys and for authorizing them.

Cockpit will prompt the user to verify unknown SSH host keys, and will write accepted host keys into ~/.ssh/known_hosts.

cockpit.js should be loaded via a script tag.

Create a new cache object. The key should be a globally unique string that describes the data being cached. This string must describe the data, across all machines and all versions of cockpit. It is customary to include a version number in the key string.

The provider is a function that will be invoked to start retrieving data for the cache. It will be passed a result function as its first argument. The result should be invoked whenever new data is available. The key argument matches the key string the cache was created with.

The provider can return an object with a close method. This method will be invoked when the cache no longer needs data from the provider.

The consumer is a function that will be passed new values when they are available, whether they come from the provider or a source in a different component/frame.

Close a cache and stop calling its consumer. If the provider was invoked, then the close() method it returned will be invoked.

This function creates a new channel for communication with the system. It returns a new channel object. The options argument is a plain object. At least the "payload" option is required, and based on the payload type, other options may be required.

The channel object returned has the following fields and methods and events. You should call the channel.close() method when done with the channel.

A valid channel will always be returned and the is ready to channel.send(). The channel may close shortly afterword due to a failure.

Will be true for an binary channel. Will be set to false if the channel is textual.

The options used to open this channel. This should not be changed.

Will be true for an open channel. Will be set to false if the channel closes.

Send a message over the channel. The contents of the message depends on the payload type of the channel. If a binary channel, then data is expected to be an Array of bytes or a Uint8Array. If not binary, then the data will be converted to a string if not already a string.

Notify the channel to tune certain parameters on the fly. The options is a plain javascript object, and the contents depend on the "payload" of the channel.

One common operation is to set "command" to "done" in the options field. To indicate that no further messages will be sent through the channel.

Returns a promise that is ready when the channel is ready, or fails if the client closes. If a callback is specified, it is attached to the promise. The promise will be rejected or resolved with the contents options passed to the channel.onready and channel.onclose events respectively.

In general it’s not necessary to wait for the channel before starting to use the channel.

Close the channel.

If options is present it can be a plain javascript object containing additional channel close options to send to the peer. If closing for because of a problem, set the "problem" field to a problem code. If options is not an object it will be treated as a "problem".

The close event will fire. A channel can also be closed by a peer or if the underlying transport closes.

An event triggered when the channel receives a message. The message is passed as a string to the handler in the data. In the case of binary channels data is an Uint8Array or an Array of bytes if the former is not supported by the browser. The contents of the message depends on the payload type of the channel.

An event triggered when the channel receives an control message in the middle of the flow. One particular use is when the command is set to "done" then no further messages will be received in the channel. The exact form of these messages depend on the "payload" of the channel.

An event triggered when the other end of the channel is ready to start processing messages. This indicates the channel is completely open. It is possible to start sending messages on the channel before this point.

An event triggered when the channel closes. This can happen either because channel.close() function was called, or if the peer closed the channel, or the underlying transport closes.

The options will contain various close information, including a "problem" field which will be set if the channel was closed because of a problem.

The HTTP origin that is being used by the underlying channel transport. This is read-only, you should not assign a value. If the browser supports window.location.origin then this will be identical to that value.

The host that this transport is going to talk to by default. This is read-only, you should not assign a value. If the value is null that means that the transport has not been setup yet.

A cross site request forgery token for use with external channels. This becomes valid once the connection is properly established.

Initialization options received over the underlying channel transport. These will be empty until connection is properly established.

Call the callback function once the underlying channel transport is initialized. This will start the initialization if not already in progress or completed. If the channel transport is already initialized, then callback will be called immediately.

In general it’s not necessary to wait for the transport before starting to open channels.

Close the underlying channel transport. All channels open channels will close. The problem argument should be a problem code string. If not specified it will default to "disconnected".

Add a filter to the underlying channel transport. All incoming messages will be passed to each of the filter callbacks that are registered.

This function is rarely used.

Filter callbacks are called in the order they are registered. If a filter callback returns false then the message will not be dispatched further, whether to other filters, or to channels, etc.

The message is the string or array with the raw message including, the framing. The channelid is the channel identifier or an empty string for control messages. If control is set then this is a control message,d and the control argument contains the parsed JSON object of the control message.

Inject a message into the underlying channel transport. The message should be a string or an array of bytes, and should be valid according to the Cockpit message protocol. If the out argument is equal to false then the message will be injected as an incoming message as if it was received on the underlying channel transport.

This function is rarely used. In general you should only inject() messages you got from a filter().

Encode binary data into a string using the Base64 encoding. The data argument can either be a string, an Array, an ArrayBuffer or a Uint8Array. The return value is a string.

Decode binary data from a Base64 encoded string. The string argument should be a javascript string. The returned data> will be an array of bytes.

You can pass Uint8Array, Array or String as an alternate constructor if you want the decoded data in an alternate form. The default is to return an Array. Note that if you use a String for the decoded data, then you must guarantee that the data does not contain bytes that would be invalid for a string.

DBus values are represented as javascript values and objects as follows:

Create a DBus client for the given bus name (eg: service name). Use the following functions to make DBus method calls, watch for events, etc. The optional options argument is a javascript plain object, and may include:

If the name argument is null, and no options other than "bus" are specified, then a shared DBus client is created. When using such a client with a DBus bus, a "name" option must be specified on various other methods in order to specify which client to talk to.

Returns a promise that is ready when the client is ready, or fails if the client closes. If a callback is specified, it is attached to the promise.

Close the DBus client. If problem is specified it should be a problem code string.

An event triggered when the DBus client closes. This can happen either because client.close() function was called, or the DBus service went away, or some other problem or disconnection.

The options will contain various close information, including a "problem" field which will be set if the channel was closed because of a problem.

An event triggered when the owner of the DBus name changes. The owner value will be the id of the name owner on the bus or null if the name is unowned. The absence of an owner should not be treated as a disconnection. However this makes it possible to take some action based on the actual status of the service, for example disconnecting a pending signal handler.

Set to the options used when creating the client. Will not change for the life of the client.

The unique DBus name of the client. Initially null, and becomes valid once the the client is ready.

Create proxy javascript object for a DBus interface. At the specified DBus object path. The proxy will have properties, methods and signals from to the DBus interface, and allows for natural interaction. If no interface is specified then the DBus bus name of the client is used. If no path is specified, then the DBus name of the client is converted to a path.

If creating lots of proxies for a given interface it is more efficient to use the client.proxies() function.

The proxy is loaded when the proxy.valid field is true, and it is set to false if the underlying interface and/or path don’t or no longer exist, or the client has closed. You can wait for proxy to become valid by passing a callback to its proxy.wait() function. The proxy.onchanged event will also fire when the proxy becomes valid or invalid. DBus properties and methods on the proxy are not defined until the proxy becomes valid.

All DBus properties on the interface that start with an upper case letter (as is convention) will be automatically defined on this proxy, and will update their values as the DBus property values change. In addition the proxy.onchanged event will fire every time the properties change.

If you assign a value to a writable property on the proxy, the proxy will try to set that property on the DBus interface at path. The actual proxy property value will not update until the DBus service has notified the proxy of the change. If setting a property fails a warning will be logged. In order to have more reliable setting of properties, or track when they have been set, or if setting fails, use the client.call() directly. It should be noted that DBus service implementations may also be inconsistent in their behavior when setting a property fails.

You can access the raw property data using the proxy.data field, including data for properties that do not start with an upper case letter.

All DBus methods on the interface that start with an upper case letter (as is convention) will be automatically defined on this proxy. These methods are called with arguments as normal javascript arguments. A Promise that will complete successfully when the method returns, or fail if an error occurs. The return values from the DBus method will be passed to the then handler function directly.

Methods that do not start with an upper case letter can be invoked by using the usual proxy.call() directly.

All DBus signals on the interface that start with an upper case letter (as is convention) will be automatically emit events on this proxy. These events will contain the signal arguments after the standard event argument.

Signals that do not start with an upper case letter can be subscribed to by using proxy.onsignal directly.

Usually a proxy asks the client to watch and notify it of changes to the relevant object or path. You can pass an options argument with the watch field set to false to prevent this.

Set to the DBus client of the proxy. Will not change for the life of the proxy.

Set to the DBus object path of the proxy. Will not change for the life of the proxy.

Set to the DBus interface name of the proxy. Will not change for the life of the proxy.

Set to true when the proxy’s DBus interface is present at its DBus path, and all information for the proxy has loaded. Is set to false while loading, and after the proxy no longer refers a DBus interface and path. Also set to false if the client closes.

Use the by proxy.wait() function to wait for a proxy to load. The proxy.onchanged event will also be emitted when the proxy becomes valid or invalid. DBus properties and methods on the proxy are not defined until the proxy becomes valid.

A plain javascript object containing all the raw property data that this proxy has loaded. This will be updated automatically as the proxy is notified of property changes from the DBus service. The proxy.onchanged event will be emitted when it changes.

Make a DBus method call on this proxy.

For DBus methods that start with an upper case letter, is usually more convenient to call the method directly on the proxy. However if methods that do not follow the usual DBus convention, or specify additional options, or the caller cannot be sure that the method actually exists, you can use this method.

This function also works on proxies that have are still loading and have not become valid yet.

The method should be a DBus method name, and the args should be an array of arguments to pass to the method. The options are described elsewhere.

The returned value is identical to the one returned from client.call(). It is a Promise that will complete successfully when the method returns, or fail if an error occurs.

Wait for a proxy to finish loading. This function returns a promise. If a callback function is passed as an argument then that function will be invoked when the proxy is ready. If this method is called after a proxy has already loaded, then the promise will be resolved immediately, and any callback will be invoked immediately. Use the promise or proxy.valid to determine whether the proxy is valid.

This event is emitted when the proxy’s properties change.

The data has the following form, and will only include properties that have changed:

This event is emitted when the proxy’s emits an event.

For most events, that have names which start with an upper case letter, you can just connect to that event as a signal directly. However if you wish to be notified when any signal is emitted, or for signals that do not follow the usual DBus convention, you can connect to this event.

The name is the DBus signal name, and the args is an array of arguments that were emitted with the signal.

Create proxy javascript objects for a DBus interfaces. The proxies will have properties, methods and signals from the DBus interface, and allow for natural interaction. If no interface is specified then the DBus bus name of the client is used. If no path_namespace is provided then "/" will be used.

Proxies will be automatically created for instances of the interface available at the DBus service. The optional path_namespace argument can be used to restrict the proxies for instances that have DBus paths which have the namespace path prefix.

The returned proxies object will is used as a dictionary, and will have values containing proxies for DBus interface instances, with the keys being the DBus paths of those instances. It is possible to enumerate over the returned proxies.

Proxies will be automatically added and removed from the proxies object as they appear and disappear in the service. The proxies.onadded and proxies.onremoved events will be emitted. DBus services may not support notifications of paths disappearing.

Use the proxies.wait() function to be notified when the initial set of proxies has been populated.

Usually a proxies ask the client to watch and be notified of changes to the relevant object or path. You can pass an options argument with the watch field set to false to prevent this.

Wait for a proxies object to populate its initial set of proxies. This function returns a promise. If a callback function is passed as an argument then that function will be invoked when the proxies are ready. If this method is called after the proxies have populated, then the promise will be resolved immediately, and any callback will be invoked immediately.

Set to the DBus client of the proxies. Will not change.

Set to the DBus interface name of the proxies. Will not change.

Set to the DBus path namespace used which the proxies must have as a DBus path prefix. Will not change.

This event is emitted when a proxy is added to the proxies object. The proxy will already have loaded.

This event is emitted when one of the proxy in the proxies object changes its properties.

This event is emitted when a proxy is removed to the proxies object.

Make a DBus method call.

The path is the DBus object path to make the call on, interface is the DBus interface for the method and method is the name of the method to call. The args is an array of arguments to pass to the method, each of which must be appropriate for the expected DBus type of that argument. The args may be null if no arguments are to be sent.

The returned value is a Promise that will complete successfully when the method returns, or fail if an error occurs.

If options is specified it should be a plain javascript object, which may contain the following properties:

This is a standard Promise method. It sets up a handler to be called when the DBus method call finishes successfully.

The args argument is an array of return values from the DBus method. Each of them will be converted to an appropriate javascript type.

The options argument may contain additional information about the reply. If the type option was specified when performing the method call, then the options in the reply here will also contain a type field containing the DBus type signature of the output. If the flags option was specified when performing the call then the options in the reply here will contain message flags. Possible out message flags are:

This is a standard Promise method. It sets up a handler to be called when the DBus method call fails.

The exception object passed to the handler can have the following properties:

Subscribe to signals. The match argument is a javascript plain object which defines what signals to subscribe to. Each property in the match argument restricts signals subscribed to. If a property is not present then it is treated as a wildcard, matching anything. If an empty object is specified as match then all signals will be subscribed to. The match argument may contain the following properties:

The handler passed as the second argument will be invoked when the signal is received. A subscription is returned which can be used to remove the subscription by calling its subscription.remove() method.

It is not a problem to subscribe to the same signals more than once, with identical or slightly different match arguments.

Unsubscribe from the DBus signal subscription.

Watch for property and interface changes on the given DBus object path DBus path_namespace. If interface is specified only properties on that DBus interface will be watched.

The client.proxy() and client.proxies() functions and the objects they return are high level wrappers around client.watch().

The property and interface changes will be available in raw form on the client.onnotify event.

Property and interface changes that are caused by a method call or signal will show up before that method call reply is received, or signal event is triggered. It should be possible to rely on this guarantee, unless the DBus service in question behaves incorrectly. Internally these watches work well with code that implements the ObjectManager portion of the DBus specification. If no ObjectManager implementation is available, the watch falls back to using DBus Introspection along with the usual PropertiesChanged signal. If the DBus service implements none of these, or implements them in an inconsistent manner, then this function will provide inconsistent or unexpected results.

The parameter is either a DBus path or a plain javascript object with zero or more of the following fields. If an empty javascript object is used as an argument, then all paths, interfaces and properties will be watched.

The returned value is a Promise that will complete successfully when the watch has populated its initial set of properties and interfaces, and these have been notified via client.onnotify.

A watch can be removed by calling the watch.remove() method on the returned value. If identical watches are added more than once, then they must also be removed the same number of times before the removal takes effect.

This is a standard Promise method. It sets up a handler to be called when the watch has populated its initial properties and interfaces.

This is a standard Promise method. It sets up a handler to be called if the watch fails to populate its initial properties and interfaces. Note that a watch will only fail if the DBus client closes or is somehow disconnected. It does not fail in the case of missing interfaces or properties.

Remove the watch. This may not have any immediate effect if other watches are in place. In particular, if identical watches are added more than once, then they must also be removed the same number of times before the removal takes effect.

An event triggered when watched properties or interfaces change.

The client.proxy() and client.proxies() functions and the objects they return are high level wrappers around the data provided by this event.

The data has the following form:

Multiple paths may be present, each of which may have multiple interfaces, each of which may have multiple properties. The first time a given path and interface is emitted from this signal, it will have all its properties and interfaces. Thereafter only changes are noted. If an interface is set to null, then that interface has disappeared.

Emits a synthetic notify event. The data argument should follow the same layout as described for the notify event.

An event triggered when the meta data about watched interfaces is loaded.

The client.proxy() and client.proxies() functions and the objects they return are high level wrappers around the data provided by this event.

The data has the following form:

Multiple interfaces may be present, each of which may have methods and properties. This is emitted before the first client.onnotify event for the relevant interface.

A DBus variant is represented as a plain javascript object with a "t" property represesting the full DBus type of the variant, and a "v" property containing the variant value.

This is a helper function for creating such a variant object.

Cockpit represents problems with standardized problem string codes.

Return a message for the exception or problem code passed as an argument. If the argument is an object with a "message" property, as is the case with most exceptions, that will be returned directly. If the argument is an object with a "problem" property, then it will be used as the problem code. An appropriate message will be returned for problem codes.

You can read a file with code like this:

It is recommended to use absolute paths. Relative paths are resolved against /. To work with the current user’s files cockpit.user() can be used to get the user’s home directory.

The read() method returns a Promise.

When successful, the promise will be resolved with the content of the file. Unless you specify options to change this (see below), the file is assumed to be text in the UTF-8 encoding, and content will be a string.

The tag that is passed to the then() callback is a short string that is associated with the file and changes whenever the content of the file changes. It is meant to be used with replace().

It is not an error when the file does not exist. In this case, the then() callback will be called with a null value for content and tag is "-".

The superuser option can be used the same way as described in the cockpit.channel() to provide a different access level to the file.

You can use the max_read_size option to limit the amount of data that is read. If the file is larger than the given number of bytes, no data is read and the channel is closed with problem code too-large. The default limit is 16 MiB. The limit can be completely removed by setting it to -1.

To write to a file, use code like this:

The replace() method returns a Promise.

When the promise is resolved, the file has been atomically replaced (via the rename() syscall) with the new content. As with read(), by default the new content is a string and will be written to the file as UTF-8. The returned tag corresponds to the new content of the file.

When the promise is rejected because of an error, the file or its meta data has not been changed in any way.

As a special case, passing the value null to replace() will remove the file.

The replace() method can also check for conflicting changes to a file. You can pass a tag (as returned by read() or replace()) to replace(), and the file will only be replaced if it still has the given tag. If the tag of the file has changed, replace() will fail with an error object that has error.problem == "change-conflict". See modify() below for a convenient way to achieve transactional updates to a file.

By default, a file is assumed to be text encoded in UTF-8, and the read() and replace() functions use strings to represent the content.

By specifying the syntax.parser() and syntax.stringify() options, you can cause read() to parse the content before passing it back to you, and replace() to unparse it before writing.

The main idea is to be able to write { syntax: JSON }, of course, but you can easily pass in individual functions or make your own parser/unparser object:

Any exceptions thrown by the parse() and stringify() functions are caught and reported as read or write errors.

The null value that is used to represent the content of a non-existing file (see "Simple reading and writing", above) is not passed through the parse() and stringify() functions.

By default the content of the file is assumed to be text encoded as UTF-8 and it can not contain zero bytes. The content is represented as a JavaScript string with read(), replace(), etc. By setting the binary option to true when creating the proxy, no assumptions are placed on the content, and it is represented as a Uint8Array in JavaScript.

Use modify() to modify the content of the file safely. A call to modify() will read the content of the file, call callback on the content, and then replace the content of the file with the return value of the callback.

The modify() method uses the read() and replace() methods internally in the obvious way. Thus, the syntax.parse() and syntax.stringify() options work as expected, null represents a non-existing file, and the watch callbacks are fired.

It will do this one or more times, until no other conflicting changes have been made to the file between reading and replacing it.

The callback is called like this

The callback is allowed to mutate old_content, but note that this will also mutate the objects that are passed to the watch callbacks. Returning undefined from the proxy is the same as returning old_content.

The modify() method returns a Promise.

The promise will be resolved with the new content and its tag, like so

If you have cached the last content and tag results of the read() or modify() method, or the last values passed to a watch callback, you can pass them to modify() as the second and third argument. In this case, modify() will skip the initial read and start with the given values.

Calling watch() will start monitoring the file for external changes.

Whenever a change occurs, the callback() is called with the new content and tag of the file. This might happen because of external changes, but also as part of calls to read(), replace(), and modify().

When a read error occurs, the callback() is called with an error as a third argument. Write errors are not reported via the watch callback.

Calling watch() will also automatically call read() to get the initial content of the file. Thus, you normally don’t need to call read() at all when using watch().

To disable the automatic reading, e.g. for large files or unreadable file system objects, set the read option to false. The first content argument of the callback will then always be null.

To free the resources used for monitoring, call handle.remove().

A string containing the path that was passed to the cockpit.file() method.

Call the close() method on a file proxy to cancel all ongoing operations, such as reading, writing, and monitoring. The proxy should not be used after closing it.

Create a new HTTP client. The endpoint can be a file path starting with / to connect to a unix socket, or it can be a port number to connect to. The optional options argument is a javascript plain object, and may include:

Here is a somewhat complex example of using most of the above options when when calling cockpit.http():

Perform an HTTP GET request for the given path. If the params is specified it should be a plain javascript object, which will be turned into a query string.

Optionally a plain javascript object containing headers can be included in the headers argument.

The return value is a Promise that will complete if the request happens successfully, or fail if there’s a problem.

Perform an HTTP POST request for the given path. The body can be a string, or a javascript plain object, which will be encoded as JSON data. If body is undefined or null then an empty HTTP body will be sent.

Optionally a plain javascript object containing headers can be included in the headers argument.

The return value is a Promise that will complete if the request happens successfully, or fail if there’s a problem.

Perform an HTTP request. The options can contain the following:

The return value is a Promise that will complete if the request happens successfully, or fail if there’s a problem.

This is a standard Promise method. It sets up a handler to be called when the request finishes successfully.

The data argument contains the body result of the request. If it a string, unless the process was opened in binary mode, in which case the data is an array of bytes. If a request.stream() handler is set up, then any standard output data consumed by the handler will not be included in the data argument.

This is a standard Promise method. It sets up a handler to be called when the request fails, or returns an error code.

The exception object passed to the handler can have the following fields:

If the request returned a response body, it will be available in the data argument. Otherwise this argument will be undefined.

This sets up a handler to be called when the HTTP request gets the initial response from the server. The status argument is the HTTP status integer, and the headers is a plain javascript object containing the headers of the response.

This sets up a handler to be called when the request returns output data. The handler will be called multiple times.

Only one handler may be registered at a time. Registering an additional handler replaces the previous one. The handler receives either string data or an array of binary bytes as its argument. A stream handler may return a number, which indicates the number of characters or bytes consumed from data. Any data not consumed will be included again the next time the handler is called.

If a request.stream() handler is set up, then the request.then() handlers will only get any remaining data not consumed by the stream handler.

This method writes data to the HTTP request body. It is only valid if no "body" has been specified in http.request() options. If stream is true then this function can be called again to provide further data.

Cancel the request. If problem is specified it should be a standard problem code string.

Cancel all outstanding requests with the given problem code. This is useful when you know that the server is going down soon.

The current locale language code. This is set based on the cockpit.locale() data loaded.

Load locale information for a given po data. The data should be JSON data in the po2json format. The data will be loaded globally. If po data has already been loaded, then this will extend that loaded data with additional strings. Any identical translations strings will be replaced with the new strings. A null argument clears all the locale information previously loaded.

Various methods such as cockpit.gettext() make use of the loaded data.

Lookup string for translation in the loaded locale data. The translated string will be returned, or string will be returned if no such translated string is present. The context argument is an optional string used to qualify the string.

This function can be assigned to a variable called _ (underscore) which will make your code work with the typical _("string") syntax.

A noop function suitable for assigning to N_ or NC_ so that gettext scanners will be able to find translatable strings. More specifically this function returns its last argument.

Lookup a string appropriate for a pluralization form of the number. Various languages have complex pluralization forms that go far between the singular and plural forms speakers of English are familiar with. If no such translated string is found then either one of string1 or stringN is returned according to simple pluralization rules.

The context argument is an optional string used to qualify the string.

The document will be scanned for translate tags and they will be translated according to the strings in loaded locale data. One or more element arguments may be specified. These are DOM elements for specific parts of the document to be translated. If no element is specified then the entire document is translated.

If an array or array-like object is passed as a selection then all DOM elements in the array will be treated as parts of the document to be translated.

Cockpit components often have different views, without changing the HTML file that is being viewed. These are known as pages. cockpit.location is an object that can be used to read the current page and to navigate to a different page location. It works by updating window.location.hash.

The cockpit.location looks like a HTTP path with a possible query string:

The location.path and location.options contain a parsed form of the location. While the location cannot be modified in place, a new one can be created by assigning a string to cockpit.location or by calling the location.go() function.

cockpit.location is designed similarly to window.location in that the location object is preplaced whenever the current page location changes. To be aware of when the page location changes listen for the cockpit.onlocationchanged event.

Using the location object as a string will result in the location.href.

In Cockpit in there multiple components shown. In order to tell Cockpit to jump to and show another component and a certain location within that component, use the cockpit.jump() function. Stable component paths are documented. Don’t assume you can navigate into paths that are not stable API.

Logout of Cockpit. Unless reload is false this will also cause the page to be reloaded, so that the user can see the logged out state.

This object contains information about the user that’s currently logged into cockpit. The following fields are defined:

Returns a promise that completes once the user information is available.

Cockpit provides a mechanism for checking if the current user satisfies a given criteria. This is meant for updating UI elements based on what actions the user can perform. It is not an access control mechanism.

For a convenient access to all page manifests, include <script src="../manifests.js"></script> into your page to register the manifests at the cockpit.manifests global variable.

You can also load ../manifests.json directly in your page, with fetch().

Opens a new metrics channel. The data retrieved will be available in the metrics.series series sink, and can be used together with cockpit.grid() objects.

The interval is in milliseconds, and is the granularity of the series data retrieved. Any grids consuming the data must have the same interval.

The cache argument is a cache identifier. If specified, then this metrics channel will share data with other metrics channels of the same identifier. Make sure to use a globally unique string.

The options argument is either a javascript plain object, or an array of those. Each object can have the following fields.

When the options argument is an array of javascript objects, then the metrics channel tries to use them in order until one succeeds. This way, you can prefer PCP as the source but fall back to internal metrics when PCP is not available, for example. The channel gives no indication which of the options has been used, and fetch and follow might use different entries from the list.

Retrieve archived metrics data between beg and end. The arguments can either be numbers, in which case they are interval based offsets, or they can be javascript Date objects.

Start retrieving live metrics data as it become available.

Stop the retrieval of metrics and release resources.

The series sink where data retrieved data will be processed.

The metrics meta data last received.

An event triggered when one of the properties on this metrics object changes.

Creates a grid object to contain series data.

The interval is the granularity of the grid. Usually this is a number of milliseconds, when used with time series data. The beg and end are the bounds of the grid. If omitted they will be set to zero for an initially empty grid.

If beg and/or end are negative (including negative zero) then they are interpreted in number of intervals relative to the current time. Thus cockpit.grid(1000, -300, -0) will create a grid for the most recent 5 minutes.

Adds a row to the grid. The returned row is a Javascript array that will contain series data. The arguments control how the row is populated from the series data. The row is a sparse array. Its row.length will not match the expected size of the grid, unless and until the row has been completely filled in. The first index of the row will contain the data from the series data at the grid.beg offset.

When no arguments are passed, an empty row is added, and it is not populated with data.

When called with a series and path argument then the row will be populated directly with series data. The series can either be a series object or an object that has an obj.series property. The series interval must match the interval of this grid. If path is missing or empty, then the series data is placed into the row directly. Otherwise path indicates which part of the series data to place in the row. When path is an array, it is used as a set of property names or array indexes to follow into nested series data. When path is a dotted string, it is split and used the same way to locate the correct value in nested series data. The exact format of the series data depends on its producer, and relevant paths will be documented there.

If a callback function is specified, then it will be invoked to provide series data for the row. The function is invoked as callback(row, index, count), where the row is the row to fill in, the index is the index to start filling in and count is the number of items to fill in. The this variable will be set to the grid while invoking the callback. The callback is called after other data rows for a given series have been filled in. Callbacks are called in the order added, unless the early argument is set to true, in which case the callback is called earlier than callbacks without the early argument set.

To remove the row use the grid.remove() method.

The row will start being populated with data when the series produces data. To make this happen right away, use the grid.sync() method.

Remove a previously added row from the grid. The row will no longer be updated with series data.

Load or reload data from the series into the rows. This does not clear the rows before populating them. Some data may be populated immediately, others may have to wait until data can be loaded. Internally this function calls series.load() for each series.

All rows with callbacks will be invoked to regenerate all the data. The grid.onnotify event will be triggered. It is not necessary to call this function after a call of the grid.move() method.

Move the grid to new beg and end range. Data will be discarded from the rows and grid.sync() will be called to load or reload series data for the new range of offsets.

If end is not specified it will be set to beg. If beg and/or end are negative (including negative zero) then they will be set to the number of intervals prior to the current time taken as an interval.

If beg and/or end are negative (including negative zero) then they are interpreted in number of intervals relative to the current time. Thus cockpit.grid(1000, -300, -0) will create a grid for the most recent 5 minutes.

Move the grid forward every grid.interval milliseconds. To stop moving forward, call grid.move().

This function is called to have rows with callbacks recalculate their data. It is not normally necessary to call this function, as it will be invoked automatically when new series data is available or has been loaded. This function triggers the grid.onnotify event.

An event that is triggered when some part of the series data in grid changes. The index is the row index where things changed, and the count is the length of the data that changed.

Close the grid, and stop updating the rows.

The granularity of the grid. For time series data this is an interval in milliseconds. In order to use a given grid and series together, their interval properties must match.

The beginning offset of the series data in the grid. Do not set this property directly. Use the grid.move() method instead.

The ending offset of the series data in the grid. Do not set this property directly. Use the grid.move() method instead.

Create a new sink of series data. This is usually done by producers of series data, and it is rare to invoke this function directly.

The interval is the granularity of the series data. For time series data this is an interval in milliseconds. If a cache string is specified, series data will be cached across frames for series with the same cache cache identifier to load and/or reload.

If a fetch callback is specified, then it will be invoked when grids request certain ranges of data. The fetch callback is invoked with function fetch(beg, end) { ... } range offsets. The series.input() should be called with data retrieved, either immediately or at a later time. The callback may be called multiple times for the same ranges of data. It is up to the callback to determine when or whether it should retrieve the data more than once.

A producer of series data, usually calls this function and creates itself a obj.series property containing this series object.

Send series data into the series sink. Any grids that have added rows based on this series, will have data filled in. The beg is the beginning offset of items. The items are an array one or more series data items.

Producers may wish to provide additional properties that can be used in lookup paths that rows can pull from. This is done in the mapping argument. If specified it is a tree of objects. Each sub object should have a property with the name "" empty string, which will be used as the property name or index in place of the one used in the lookup path.

Load data from the series into any grids that have rows based on this series data. Any cached data will be filled in immediately. Any data not cached, will be requested from the producer, if possible, and may arrive at a later time.

The beg and end denote the range of data to load.

The granularity of the series. For time series data this is an interval in milliseconds. In order to use a given grid and series together, their interval properties must match.

The maximum number of items to cache for loading and/or reloading. You can change this value to a different number. Having a number close to zero will break certain usage of grids, such as grid.walk().

Spawns a process on the system.

The args should be an array starting with the executable and containing all the arguments to pass on the command line. If args is a string then it is interpreted as an executable name. The optional options argument is a javascript plain object and can contain any of the following fields:

The spawned process is a promise that will complete if the process exits successfully, or fail if there’s a problem. Some additional methods besides the standard promise methods are documented below.

The standard output of the process is made available via the spawned process object. Any non-UTF8 output from the process will be coerced into textual form. It is highly recommended that only textual output be produced by the command. The standard error is logged to the journal.

Run a shell script on the system.

This function spawns a Bourne shell script process. The full text of the /bin/sh shell script should be passed in as the first argument. The args can be an array of arguments, not including the executable, which are passed to the script as $1, $2 and so on. Shebang options are not used or respected.

The options is an optional javascript plain object and can include any of the fields listed for the cockpit.spawn() function.

The spawned process is a promise that will complete if the script exits successfully, or fail if there’s a problem. Some additional methods besides the standard promise methods are documented below.

The standard output of the process is made available via the spawned process object. Any non-UTF8 output from the process will be coerced into textual form. It is highly recommended that only textual output be produced by the command. The standard error is logged to the journal by default.

This is a standard promise method. It sets up a handler to be called when the process finishes successfully.

The data argument contains the standard output of the process. If it a string, unless the process was opened in binary mode, in which case the data is an array of bytes. If a process.stream() handler is set up, then any standard output data consumed by the handler will not be included in the data argument.

If the process was spawned with the "err" option set to "message" then the second argument will contain the standard error output of the process.

This is a standard Promise method. It sets up a handler to be called when the process fails, terminates or exits.

The exception object passed to the handler can have the following fields:

If the process actually ran and produced output before failing, it will be available in the data argument. Otherwise this argument will be undefined.

This sets up a handler to be called when the process has standard output. The handler will be called multiple times. The handler will be called regardless of whether the process ends up exiting successfully or not.

Only one handler may be registered at a time. Registering an additional handler replaces the previous one. The handler receives either string data or an array of binary bytes as its argument. A stream handler may return a number, which indicates the number of characters or bytes consumed from data. Any data not consumed will be included again the next time the handler is called.

If a process.stream() handler is set up, then the process.then() handlers will only get any remaining data not consumed by the stream handler.

This method writes data to the standard input of the process. If data is null or undefined it is not sent. The data should be a string or an array of bytes if the process was opened in binary mode.

If stream is set to true then this function may be called again with further input. Otherwise the standard input of the process is closed.

Close the process by closing its standard input and output. If problem is specified it should be a standard problem code string. In this case the process will be terminated with a signal.

Format a string interpolating args into template using shell like syntax. The args may be either an array or javascript object. The template can contain fields that look like $name or ${name} or $0. Numeric fields are used with array args and start at zero.

In the second form, multiple arg arguments may be passed directly, and interpolated as as numeric fields in the template.

All falsy arguments except the numbers 0 and `0.0`are replaced by an empty string.

Formats number into a displayable string. If the number is not an integer, it is rounded to the given number of decimal places, defaulting to 3. If the number is near zero, but not quite zero it is rounded to the smallest non-zero value of the given precision; i.e. ±0.001 for default precision 3.

If number is null or undefined an empty string will be returned.

Formats number into a displayable string with a suffix, such as kB or MB.

By default, SI units are used. IEC units (1024-based) can be requested by including base2: true in options.

By default, non-integer numbers will be formatted with 3 digits of precision. This can be changed with options.precision.

If number is null or undefined an empty string will be returned.

Format number of bytes into a displayable speed string.

This function is mostly equivalent to cockpit.format_bytes() but the returned value contains a unit like kB/s or MB/s.

Format number of bits into a displayable speed string.

This function is mostly equivalent to cockpit.format_bytes() but the returned value contains a unit like kbps or Mbps.

This function does not support IEC units. base2 may not be passed as part of options.

Requests initialization of the Cockpit client library. This will ensure that the transport is connected and we are ready to create channels. It also populates the cockpit.info field.

This function returns a promise. Initialization isn’t complete until the promise has resolved. You can either await it or call .then() on it.

This object contains information about Cockpit itself. It is only available after cockpit.init() has been called and awaited.

Adds an EventTarget implementation to the object. Optionally store the handlers in handlers if its specified.

This is a Cockpit component that brings up system log viewer, with filtering capabilities. On systemd based systems this displays the entries from journal.

This is a Cockpit component that brings up a web-based terminal for the logged in user.