Bootstrapping a network of Cockpit managed machine - cockpit-project/cockpit GitHub Wiki

This page is out of date

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.

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?

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.

<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)

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.

The cockpit-setup utility is pretty much the same as cockpit-web, but interacts on the command line and without doing anything about accounts.

• Progress reporting.

• Enrolling in multiple domains. As written, Initial Setup will enroll a machine in exactly one (the given) domain.