DOCSEARCHbyAlgolia
Submit Docs

Cockpit Linux Server Administration Interface

repository·main·Indexed 12 days ago

https://github.com/cockpit-project/cockpit

A lightweight, web-based administration interface for Linux servers that provides a bridge between a web browser and a real Linux session. It enables management of system resources, networking, storage, and logs, and supports multi-host management via SSH. The project includes a web server (cockpit-ws), a TLS proxy (cockpit-tls), and specialized container deployments for environments like Fedora CoreOS and Kubernetes.

Tokens
69.1K
Snippets
227
Records
313
Agent score
97%

What's inside Cockpit

  1. Overview of the Cockpit webserver container

    main
    The cockpit/ws container image provides the Cockpit web server and a minimal set of built-in Cockpit pages (such as cockpit-system). It is designed for deployment on container hosts like Fedora CoreOS or Kubernetes where installing RPMs directly on the host is difficult. This container acts as the 'entry point' for browsers, connecting to local or remote machines via SSH to provide a Cockpit UI.

  2. Overview of Cockpit Containers

    main

    Cockpit uses several specialized containers for different environments and development tasks:

    • ws: The standard Cockpit web server container. It is designed for installation on CoreOS and uses SSH to connect to the local host or remote machines.
    • bastion: A prototype, reduced variant of the web server. It runs unprivileged and is restricted to connecting only to remote machines, making it suitable for deployments in environments like Kubernetes.
    • unit-tests: A container used to run the project's unit tests. It is used in GitHub PRs but can be run locally to reproduce failures.
    • flatpak: Contains scripts for locally building, running, and testing the Cockpit Client flatpak.

  3. What is Cockpit?

    main

    Cockpit is a lightweight, interactive web-based interface for Linux server administration. It allows sysadmins to manage servers directly from a browser by interacting with a real Linux session.

    Key capabilities include:

    • System Administration: Manage containers, storage, and network configurations.
    • Observability: Inspect system logs via the journal interface.
    • Terminal Integration: Seamlessly switch between the web UI and a terminal; actions taken in the UI (like starting a service) are reflected in the terminal, and terminal errors are visible in the Cockpit journal.
    • Multi-host Management: Easily add and jump between multiple Linux hosts that have Cockpit installed and are accessible via SSH.

  4. Understand the role of cockpit-ws

    main

    The cockpit-ws program is the web service component of Cockpit. It acts as the communication layer between the browser-based application and various backend configuration tools and services (such as cockpit-bridge).

    In standard installations, users and administrators should not start this program manually; it is automatically managed by systemd via cockpit-tls during bootup.

  5. How Cockpit selects branding files

    main

    Cockpit determines which branding assets (logos, icons, CSS) to serve by searching through a specific hierarchy of directories. It uses the $ID and $VARIANT_ID variables from the system's /etc/os-release file.

    Administrators can override all system branding by placing custom files in /etc/cockpit/branding/ (or more generally, $XDG_CONFIG_DIRS/cockpit/branding/). This directory is checked first.

    If no local override is found, Cockpit searches the following directories in order:

    1. $prefix/share/cockpit/branding/$ID-$VARIANT_ID
    2. $prefix/share/cockpit/branding/$ID
    3. $prefix/share/cockpit/branding/default
    4. $prefix/share/cockpit/static

    Note: $prefix is typically /usr. All files in these directories are served over HTTP without authentication to ensure they are available for the login screen.

  6. How Cockpit Storage works in Anaconda mode

    main

    When the Anaconda OS Installer opens the Cockpit "storaged" page, Cockpit enters a special "Anaconda mode". In this mode, the storage interface restricts itself to the target installation environment. It hides the real root filesystem (e.g., the Live USB environment) and allows the user to create a "fake" root filesystem on a target block device.

    To enter Anaconda mode, the installer must store a cockpit_anaconda item in the browser's window.sessionStorage. This item must be a JSON-encoded object containing configuration details such as available devices, mount point prefixes, and boot mode.

  7. How Cockpit uses storaged for storage management

    main

    Cockpit leverages the storaged project (if available on the system) to configure and monitor storage, disks, mounts, and other storage-related components. This functionality is provided via the Cockpit storaged package.

    Key features supported through storaged include:

    • LVM (Logical Volume Manager)
    • iSCSI
    • Multipath
    • BTRFS

    Note on udisks: While Cockpit can use udisks, it disables several storage-related features (such as updating /etc/fstab and /etc/crypttab) when using udisks to ensure system stability.

  8. How multi-host management works in Cockpit

    main

    Cockpit allows you to manage multiple hosts within a single browser session by establishing SSH connections to remote hosts.

    Security Warning: Unlike a standard command-line ssh session, code from the local host and all connected remote hosts runs simultaneously in the same browser context. They are not isolated from each other. Any remote host you connect to has the same privileges as your primary session and can execute JavaScript in your browser. Only connect to remote hosts that you trust.

  9. Understand the lifecycle of a Cockpit channel

    main

    A channel follows a specific lifecycle of control messages and data updates:

    1. Opening: The client sends an open command.
    2. Ready: The server immediately sends a ready message.
    3. Initialization: The server sends one or more patches to modify the initial value (which is null) until an "initial state" is reached (an object without a partial attribute).
    4. Watch Mode:
      • If watch: false: The server sends done immediately and closes the channel.
      • If watch: true: The channel remains open. The server sends updates as changes are detected (e.g., transitions between info and problem).
    5. Closing: The channel stays open until the client explicitly closes it. The server may send a close message containing error details like message or tag.

  10. How Cockpit components work together

    main

    Cockpit's architecture relies on two primary components to bridge the web browser to the Linux system:

    1. cockpit-ws: The web service that listens on port 9090. It is started on demand by systemd. Its responsibilities include authenticating the user and loading the Cockpit application into the browser.
    2. cockpit-bridge: A process started within a Linux user session (similar to a shell). It provides the web browser with access to system APIs by communicating via its standard input (stdin) and standard output (stdout).

  12. How Cockpit processes start and exit

    main

    Cockpit uses a demand-driven startup model via systemd socket activation.

    1. Startup: When a browser accesses cockpit.socket (typically on port 9090), the cockpit.service and cockpit-ws processes start automatically. After a user logs in, a cockpit-bridge process is started within a Linux user login session.
    2. Remote Hosts: For systems added via the host switcher, the bridge is started via SSH on demand, so only the target system needs cockpit.socket enabled.
    3. Shutdown/Exit:
      • The cockpit-bridge process exits when the user logs out.
      • The cockpit-ws process exits automatically after 10 minutes of inactivity.
      • The browser will automatically disconnect if it loses contact with cockpit-ws for 30 seconds.