How to Install Cockpit on Ubuntu 18.04

This article was originally published on Alibaba Cloud. Thank you for supporting the partners who make SitePoint possible.

Cockpit is a server manager that makes it easy to administer your GNU/Linux servers via a web browser. It makes Linux discoverable, allowing sysadmins to easily perform tasks such as starting containers, storage administration, network configuration, inspecting logs and so on.

Cockpit provides convenient switching between the terminal and the web tool. A service started via Cockpit can be stopped via the terminal. Likewise, if an error occurs in the terminal, it can be seen in the Cockpit journal interface. Using Cockpit you can monitor and administer several servers at the same time. Just add it easily and your server will look after its buddies.

Cockpit is released under the LGPL v2.1+, and it is available for Redhat, CentOS, Debian, Ubuntu, Atomic, and Arch Linux. Cockpit is compatible and works well with Alibaba Cloud Elastic Compute Service (ECS) servers. In this tutorial, I will be installing Cockpit on an ECS with Ubuntu 18.04 LTS installed on it. Until Ubuntu 18.04 matures and is included in Alibaba Cloud’s library of operating system images, we can upgrade Ubuntu 16.04 to Ubuntu 18.04 by using the do-release-upgrade utility.

Prerequisites

1. You must have Alibaba Cloud Elastic Compute Service (ECS) activated and verified your valid payment method. If you are a new user, you can get a free account in your Alibaba Cloud account. If you don’t know about how to setup your ECS instance, you can refer to this tutorial or quick-start guide.
2. You should set up your server’s hostname.
3. Access to VNC console in your Alibaba Cloud or SSH client installed in your PC.

After completing the prerequisites, log in as root user with your root username & password via SSH client (e.g. Putty) or VNC console available in your Alibaba Cloud account dashboard.

Install Cockpit on Ubuntu 18.04

Cockpit is included in Ubuntu 18.04, so you can just use apt command to install it.

sudo apt update

Install the Cockpit package.

sudo apt -y install cockpit

Start and enable the Cockpit.

sudo systemctl start cockpit.socket
sudo systemctl enable cockpit.socket

Working with Cockpit

Once you start the Cockpit service, it will start listening on port 9090. Now, open up your browser and navigate it to below URL.

https://ip-address:9090

Cockpit uses a self-signed SSL certificate for secure communication. So, you need to add an exception in your browser to access the Cockpit.

Log in with your local user account. In my case it is gqadir.

If the user is a non-privileged user and has sudo access, then tick mark Reuse my password for privileged tasks.

We must now insert our credentials in the related input fields and click on the Log In button. Once logged in we will be redirected to the main cockpit page:

Let’s take a look at it. The main page section shows us some information about the machine we are running on, as the hardware, hostname, operating system and system time. In this case I am running Ubuntu on a virtual machine, therefore the value of the hardware section is QEMU Standard Pc.

We also have a dropdown menu which let us perform a power option on the system as restart or shutdown. On the right we can see some graphs which let us monitoring crucial system activities, in order: CPU and memory usage, disk activity and network traffic.

The Logs Section

In the left column menu, just below the system section, we can click on logs to access to the page dedicated to system logs. Here, at the top of the page, we have two nice menus which let us filter the logs by period of time and severity, choosing between problems, notices, warnings and errors.

To access detailed information about a log message, all we have to do is to click on the corresponding row: we will be redirected to a page containing the log details.

The Storage Section

Proceeding further, we have the storage session. Here we have some graphs displaying disks reading and writing activities, and immediately after a status bar indicating the filesystems usage amount. We have also the option to easily add NFS Mounts and Raid Devices.

We could inspect a specific drive by clicking on the related section on the right in the Drives box: we will also be able to create a new partition table (if some conditions are respected – the disk must not be mounted, for example) on the specified drive: the operation will erase all the data on it.

The Network Section

In the section dedicated to network monitoring and administration, it’s possible to observe graphs about sent and received packets for each interface, and network activity in general. Details about an interface, such as its MAC address are visible by clicking on an interface row: here we also have the chance to enable or disable said interface. It’s also possible to easily add a bond, a bridge or a vlan using the dedicated buttons. On the bottom of the page the network logs are shown.

The Accounts and Services Sections

The last two available sections are about accounts and services management. In the former we can very easily create, delete or obtain information about the users available on the system. By clicking on a specific user section we will have the option to change its password, lock its account and even add authorized public ssh keys:

In the services section, we will be presented with an overview of system daemons and targets. The web interface grants us the ability to start, stop, enable or disable each service, showing us its current state. Thanks to cockpit, we can also easily manage systemd targets (the equivalent of classic system runlevels), sockets and timers.

Let’s now look at how we can configure Cockpit for our applications.

1. Cockpit Configuration File – cockpit.conf

Cockpit can be configured via /etc/cockpit/cockpit.conf. That file has an 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.

WebService

Origins

By default, cockpit will not accept crossdomain websocket connections. Use this setting to allow access from alternate domains. Origins should include scheme, host and port, if necessary.

 [WebService]
 Origins = https://somedomain1.com  
 https://somedomain2.com:9090

ProtocolHeader

Configure cockpit to look at the contents of this header to determine if a connection is using tls. This should only be used when cockpit is behind a reverse proxy, and care should be taken to make sure that incoming requests cannot set this header.

 [WebService]
 ProtocolHeader = X-Forwarded-Proto

LoginTitle

Set the browser title for the login screen.

LoginTo

When set to true the Connect to option on the login screen is visible and allows logging into another server. If this option is not specified then it will be automatically detected based on whether the cockpit-ssh process is available or not.

RequireHost

When set to true cockpit will require users to use the Connect to option to specify the host to log into.

MaxStartups

Same as the sshd configuration option by the same name. Specifies the maximum number of concurrent login attempts allowed. Additional connections will be dropped until authentication succeeds or the connections are closed. Defaults to 10.

Alternatively, random early drop can be enabled by specifying the three colon separated values start:rate:full (e.g. “10:30:60”). Cockpit will start refusing authentication attempts with a probability of rate/100 (30%) if there are currently start (10) unauthenticated connections. The probability increases linearly and all connection attempts are refused if the number of unauthenticated connections reaches full (60).

AllowUnencrypted

If true, cockpit will accept unencrypted HTTP connections. Otherwise, it redirects all HTTP connections to HTTPS. Exceptions are connections from localhost and for certain URLs (like /ping ). Defaults to false.

UrlRoot

The root URL where you will be serving cockpit. When provided cockpit will expect all requests to be prefixed with the given url. This is mostly useful when you are using cockpit behind a reverse proxy, such as nginx. /cockpit/ and /cockpit+ are reserved and should not be used. For example /cockpit-new/ is ok. /cockpit/ and /cockpit+new/ are not.

Log

Fatal

The kind of log messages in the bridge to treat as fatal. Separate multiple values with spaces. Relevant values are: criticals and warnings.

OAuth

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 to be configured to verify and allow Bearer tokens.

URL

This is the url that cockpit will redirect the users browser to when it needs to obtain an oauth token. Cockpit will add a redirect_uri parameter to the url with the location of where the oauth provider should redirect to once a token has been obtained.

ErrorParam

When an oauth provider redirects a user back to cockpit, look for this parameter in the querystring or fragment portion of the url to find an error message. When not provided it will default to error_description.

TokenParam

When an oauth provider redirects a user back to cockpit, look for this parameter in the querystring or fragment portion of the url to find the access token. When not provided it will default to access_token.

2. Cockpit Web Service – cockpit-ws

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(8).

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

cockpit-ws [--help] [--port PORT] [--no-tls] [--local-ssh] [--address ADDRESS]

Transport Security

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. 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 last one containing a BEGIN PRIVATE KEY or similar. The key may not be encrypted.

If there is no TLS certificate, a self-signed certificate is automatically generated using 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.

$ sudo remotectl certificate

If using certmonger to manage certificates, following command can be used to automatically prepare concatenated .cert file:

CERT_FILE=/etc/pki/tls/certs/$(hostname).pem
 KEY_FILE=/etc/pki/tls/private/$(hostname).key

 getcert request -f ${CERT_FILE} -k ${KEY_FILE} -D $(hostname --fqdn) –
 C "sed -n w/etc/cockpit/ws-certs.d/50-from-certmonger.cert 
 ${CERT_FILE} ${KEY_FILE}"

Timeout

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

Options

Command	Description
–help	Show help options.
–local-ssh	Normally cockpit-ws uses cockpit-session and PAM to authenticate the user and start a user session. With this option enabled, it will instead authenticate via SSH at 127.0.0.1 port 22.
–port PORT	Serve HTTP requests PORT instead of port 9090. Usually Cockpit is started on demand by systemd socket activation, and this option has no effect. Update the ListenStream directive cockpit.socket file in the usual systemd manner.
–address ADDRESS	Bind to address ADDRESS instead of binding to all available addresses. Usually Cockpit is started on demand by systemd socket activation, and this option has no effect. In that case, update the ListenStream directive in the cockpit.socket file in the usual systemd manner.
–no-tls	Don’t use TLS.

Environment

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.

3. Remote Access Configuration – remotectl

The remotectl program will configure remote access to the system. Currently it manages cockpit’s SSL certificate.

remotectl {COMMAND} [OPTIONS...]

Commands

Certificate

Manage Cockpit’s SSL certificate. If used without options will check if cockpit has a valid certificate without making any changes.

–ensure Ensure that a certificate exists and can be loaded. Certificate will be created if it does not already exist.

–user username The unix user that should own the certificate. Only takes effect if used with –ensure.

–group groupname The unix group that should read the certificate. Only takes effect if used with –ensure.

If any additional arguments are given, they are treated as files that should be combined to create a certificate file. If the combined files validate, they will be saved in the appropriate location using the name of the first file given with the extension changed to .cert. For example:

remotectl certificate server.pem chain.pem key.pem

will result in server.cert. If server.cert already exists it will be overwritten.

Options

Command	Description
–help	Show help options.
–verbose	Print verbose messages about the task.

4. Cockpit Host Bridge – cockpit-bridge

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.

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

Options

Command	Description
–help	Show help options.
–interact=boundary	Interact with the raw cockpit1 protocol. Useful for debugging and testing. Specify a boundary which should be on an empty line between messages.
–packages	List all available Cockpit packages and exit. Note this includes packages available to the user running this command.

Conclusion

Although not a full substitute for the command line, Cockpit gives us the opportunity to have a nice graphical overview of the core components and overall status of a machine. Multiple machines can be managed, by adding them to the main Cockpit server, that is the machine on which the service it’s running on. Daily tasks are easily accomplished through the web interface we just took a tour of: try it, it could make your life easier!

Frequently Asked Questions about Installing Cockpit on Ubuntu 18.04