Bootstrapping a network of Cockpit managed machine

This page is out of date

Introduction

Cockpit consists of roughly two parts: the interface and the agent. The interface is a web application running in a browser. The agent is a daemon accessed by the interface, via SSH or locally.

In a Cockpit managed network of machines, any machine can normally provide the interface and any machine can normally access the agent on any other machine.

Requirements

To provide the interface, a machine must

have the "cockpit" package
have a valid certificate for HTTPS
have the Cockpit TCP port open

To provide access to the agent, a machine must

have the "cockpit" package
have the SSH port open

A machine may benefit from

being able to retrieve packages from RHN/RHUI/Satellite/yum repo
being registered in a FreeIPA/RHIdM domain for SSH key management/server certificate dispatch
being registered in a Red Hat Satellite to offer Cockpit from Satellite (wish list)
advertise its existence and configuration via OpenSLP
have user accounts with the same password as the accessing machine

Q: what about other centralized authentication means?

Approach

Each interface server has a local database of known machines and their group memberships. This database can be managed explicitly via the interface. We try to keep the databases of multiple interface servers synchronized (via undecided means).

The dashboard is constructed from the database of the interface server. For now, we only have a single "dashboard" group and Cockpit just tries to connect to the agent on all machines in that group.

The user can explicitly add a machine to the dashboard group by giving its IP address or DNS name or picking it from a list of machines that have been discovered by OpenSLP.

Making a machine ready to be used with Cockpit happens in two phases: installation plus basic configuration, and initial setup.

The first phase, installation and basic configuration happens without help from Cockpit as part of the normal OS installation or as part of basic package management. Nothing more than "yum install cockpit", really.

The result is:

Cockpit code is available in a suitable version for the OS, including cockpit-ws and cockpit-agent.
realmd is installed.
SSH is accessible on port 22.
OpenSLP is configured and the machine advertises the "cockpit-agent" service.
Cockpit-ws is not enabled, there is no TLS certificate for it, and the Cockpit TCP port is firewalled.

The second phase, initial setup, is performed either by the cockpit-setup command-line utility or via Cockpit itself from a second machine.

The very first machine is typically setup by running cockpit-setup on the command line.

Additional machines are setup by logging into Cockpit on the first machine and adding the additional machines to the dashboard. This will guide the user to run the Initial Setup procedure.

Initial setup takes care of:

Setting a hostname
Joining a domain
Acquiring a TLS certificate
Opening the firewall for the Cockpit TCP port
Creating missing local user accounts

The parameters are:

Hostname
Whether cockpit-ws should be enabled.
Whether a domain should be joined.
If a domain should be joined:
- Domain name
- OU
- User for joining
- Password for joining
List of user accounts to create. For each user account:
- Real name
- User name
- Avatar
- Password hash

The Initial Setup procedure is 'idem potent'; you can execute it as many times as you like with the same parameters and you get the same result (unless there are errors).

The Initial Setup procedure can take a system in any configuration and move into the one specified by the parameters. For example, if the system is already enrolled in a different domain, it will unenroll it first. If a user account exists already, it will be updated to have the given real name, avatar, and password.

Initial setup is implemented inside cockpitd and accessed over D-Bus. The cockpit-setup utility talks to cockpitd directly, and Cockpit talks to it via cockpit-agent, in the usual fashion.

The cockpitd D-Bus API also indicates whether Initial Setup has been completed.

cockpitd

<property name="InitialSetupComplete" type="b" access="read"/>

<!-- Extent @parameters with probed defaults
-->
<method name="GetInitialSetupDefaults">
  <arg name="parameters" type="a{sv}" direction="in"/>
  <arg name="defaults" type="a{sv}" direction="out"/>
</method>

<method name="GetAdminAccounts">
  <arg name="accounts" type="aa{sv}" direction="out"/>
</method>

<method name="InitialSetup">
  <arg name="parameters" type="a{sv}" direction="in"/>
</method>

Parameters:

hostname (s)
enable-webserver (b)
domain (a{sv})
- name (s)
- ou (s)
- user (s)
- password (s)
accounts (aa{sv})
- user-name (s)
- real-name (s)
- password-hash (s)
- avatar (s, data:// url)

cockpit-web

Adding a machine to the dashboard that doesn't have initial its setup completed will launch into the setup immediately. If the setup fails, the machine is not added.

The first machine will call GetInitialSetupDefaults on the second machine and populate the dialog with it. Default domain will come from the current domain of the first machine.

The first machine will call GetAdminAccounts on itself and on the second machine, and will show the missing and mismatching ones in the UI. The user can decide for each account whether to create/update it.

Then the first machine calls InitialSetup on the second one. It passes everything from GetInitialSetupDefaults through that hasn't been explicitly changed.