Skip to content

Instantly share code, notes, and snippets.

@Micrified

Micrified/Internal_Structure_Report.md

Created March 12, 2019 12:46
Show Gist options
  • Save Micrified/574f8dd060a7835b2172775dfcfb3f25 to your computer and use it in GitHub Desktop.
Save Micrified/574f8dd060a7835b2172775dfcfb3f25 to your computer and use it in GitHub Desktop.
Download ZIP
The Internal Structure of the Project
Raw
Internal_Structure_Report.md

Cockpit Project Structure

The Source Directory

The Cockpit project's src directory contains a series of modules organizing the source code for the webserver, authentication services, data-parsing routines, and internal communication protocols. The subdirectories are listed below with their respective contents. Finally, most of the directories contained within the project contain testing files prefixed with "test", auxillary testing files suffixed with "samples", or "mock" files. A smattering of other kinds of make files and configuration files are also present. In the interest of documenting the functionality most central to the project, I've chosen to elide those from the summary below.

  • common: Common contains the core functionality of the project, namely the webserver and internal message passing facilities. The following files contain the most important components of the source code. All files listed here are written in C

    • cockpitwebserver: The webserver source code (request handlers)
    • cockpitwebresponse: Builder APIs for HTTP responses and data queues
    • cockpitwebinject: Filters for matching and injecting data
    • cockpitversion: Versioning mechanism
    • cockpitunixsignal: Custom mechanism for handling signals file reading facilities (),
    • cockpitunixfd: Custom file and directory reading facilities
    • cockpitunicode: String encoding and validation routines
    • cockpittransport: Send and receive functions with custom data-types for internal communication protocol
    • cockpittest: Testing facilities for JSON encoded data and internal commuications
    • cockpitsystem: Reads host OS version, system times, and session information
    • cockpitpipetransport: Custom pipe messaging routines used for internal communication
    • cockpitpipe: Special queued pipe with rate control mechanisms for internal use
    • cockpitmachinesjson: Converts JSON encoded data to and from a custom data structure used internally
    • cockpitlog: Mechanism for generating logs for the logging facilities
    • cockpitjson: Contains the custom JSON internal representation types, along with functions for manipulating, comparing, and extracting information
    • cockpitframe: Parsing functions for internal message frame format
    • cockpitflow: An interface for a rate-adjustable communication protocol
    • cockpitconf: Parses the cockpit configuration file
    • cockpitchannel: Implementation of internal communication channel based on communication protocol
    • cockpitauthorize: Authorization routines, using a nonce, subject, and challenge

    The directory contains many more supporting files such as hashing routines, memory sanitization, localization, error handling, and encoding/decoding facilities for more or less generic use.

  • ws: WS contains a lot of boilerplate code for handling web socket communications, particularly those associated with logging in and authentication. All files listed here are written in C

    • session: Functions for creating and managing an authenticated user session with the webserver
    • remotectl-certificate: Handles the creation and validation of user certificates
    • main: Sets environment variables, initializes logging, starts the webserver, and cleans up after execution finishes
    • cockpitwebservice: Handles initialization and closure of custom web sockets. Provides low-level web-socket communication protocols
    • cockpithandlers: Handlers for resource access, shell use, login, and on-login actions
    • cockpitcreds: Functions for interacting with creditions on the webserver
    • cockpitchannelsocket: Channels for websockets
    • cockpitchannelresponse: Injection facilities for channels
    • cockpitbranding: Retreives branding data (css, html) to be served
    • cockpitauth: Session authentication, reset, and protocol functions

  • websocket: Websocket mostly holds the basic communication code for websockets, independent of any Cockpit related functionality. All files listed here are written in C

    • websocketserver: Creates server-side web sockets for communication, includes setup of basic I/O steams and handshakes
    • websocketconnection: API modelled after W3C API for interacting with websockets. Describes abstract class and methods that should be implemented
    • websocketclient: Data structure for a client websocket. Contains necessary request/response handlers for negotiating a handshake and other initialization needs
    • websocket: Functions for parsing data received over a websocket. Mostly concerned with headers

  • ssh: SSH holds functions for extracting ssh information from the OS, and setting up a relay for use with Cockpit. All files listed here are written in C

    • ssh: Sets up an ssh relay for Cockpit
    • cockpitsshrelay: Complete ssh implementation with cockpit-specific relay integrated
    • cockpitsshoptions: Sets and gets environment variables from the OS for ssh usage
    • cockpitsshknownhosts: Parsing functions for known ssh hosts (file read from file-system)

  • retest: Small directory containing retest.c, retest.h, and their associated makefile. They are all C files

    • retest: Abstract testing routines for user-defined functions

  • pam-ssh-add: Testing functionality for SSH used with Cockpit. All listed files are C source files

    • pam-ssh-add: Contains some sort of agent for performing tests or other interactions with Cockpit's ssh

  • bridge: Bridge contains the DBus daemon, and all supporting functionality. This includes custom websockets, channels, pipes, and functions for monitoring files, directories, parsing JSON, and exchanging messages between components. All the work of reading and transmitting information between components has been abstracted into a channel like structure. This is then extended for all kinds of functions, and used to perform most of the communication in Cockpit. As usual, all the listed files are written in C

    • cockpitwebsocketstream: Defines structures and implements methods/handlers for interacting with channels that behave like websockets (use within Cockpit)
    • cockpitstream: Stream with queued input/output based on GIOStream (a pipe like mechanism)
    • cockpitrouter: Manages channel groups, communication rules, and who/where to send messages to via channels. Allows bridges and handlers to be setup
    • cockpitpolkitagent: Defines routines used by an agent that interacts with polkit (privelege management system for UNIX)
    • cockpitpipechannel: A cockpit channel that sends messages from a regular socket or file descriptor
    • cockpitpeer: Defines a peer, which does bridging (forwards messages between different channels)
    • cockpitpcpmetrics: Extracts, encodes, and transmits PCP metrics (basic summary of the system)
    • cockpitpcp: Runs Cockpit-PCP from within a Cockpit Session
    • cockpitpaths: Add, remove, and search functionality for a search path tree used internally by Cockpit
    • cockpitpackages: Contains a mechanism of checksums and parsing routines for allowing Cockpit to reload packages / manifests that have changed when running
    • cockpitmetrics: Routines for sending Cockpit metrics down a channel
    • cockpitinternalmetrics: A Cockpit channel that pulls metric data from internal sources (CPU usage, memory usage, network interface, etc)
    • cockpitinteracttransport: Used to shuttle data over a Cockpit pipe connected to standard input/output and helpful for debugging
    • cockpithttpstream: Defines an http client as a set of http connections. Caches connections and address info. Also has Cockpit channels representing http requests/responses. Includes encoding/decoding routines, keep-alive functionality, and functions for sending and receiving responses
    • cockpitfswatch: Defines a Cockpit channel type for watching a file-system. Monitors events and transmits them
    • cockpitfsreplace: A Cockpit channel for receiving from a channel and writing to files is defined here
    • cockpitfsread: A Cockpit channel for reading the contents of a file and transmitting the data
    • cockpitfslist: A Cockpit channel for listing directories or listening for events. Uses some "hacks"
    • cockpitechochannel: Special Cockpit channel which doesn't receive or send messages except for echo
    • cockpitdbussetup: Populates and loads/saves information about users within Cockpit. Password changing mechanisms mentioned in code
    • cockpitdbusrules: Forwarding rules for the dbus daemon. Helps with client subscriptions to signals and watched paths/interfaces
    • cockpitdbusprocess: Lookup functions and property extraction routines for dbus processes
    • cockpitdbusmeta: Builder functions for converting process arguments into JSON, and parsing the back (marshalling)
    • cockpitdbusmachines: Functions for retreiving properties, setting properties, and signaling changes to machines (term is unspecific)
    • cockpitdbusjson: Cockpit channel designed to send DBus messages with JSON formatted payloads (parse/build functions). Holds testing functionality as well
    • cockpitconnect: Handlers for socket connections, address enumeration, lookups, and other connection functionality
    • cockpitdbuscache: Functions for holding a cache of properties that apparently track updates. Performs introspection to get interface information
    • cockpitdbususer: Helper functions for extracting the user name, id, home, shell information, and groups
    • cockpitdbusinternal: Interface for interacting with UNIX I/O Streams
    • bridge: Main program for setting options, environment variables. Holds starter functionality for the dbus daemon, channels, file monitors, and other routing facilities used by Cockpit
    • askpass: Handles password messages used when authenticating to cockpit. Writes control messages to sockets (specifics ambiguous)

  • branding: Contains subdirectories with favicons, css, and autoconf files sorted into subdirectories by Linux distribution or container manager

  • base1: Contains the Javascript used with Cockpit, along with its style sheets and a large amount of Javascripting testing files. Files listed are a mix of css and Javascript source files

    • cockpit.js: All javascript functionality made available to the user by the webserver
    • cockpit.css: Style sheets for adjusting the appearance of Cockpit

The Test Directory

  • avocado: Contains test files for Avocado automated testing framework and Selenium. The files are written in Python. The following information regarding the tests is directly extracted from the README.md contained in the directory. Pure avocado tests use "testlib and testvm with sizzle.js CSS selector engine". These testing images are used to run the tests. Selenium is run with either remote drivers, or direct use of local browsers. The author readme cites the "getting started" documentation as a source for how they use Selenium with local browsers
  • common: Micellaneous testing files written in Python, along with some symlinks
  • containers: Python files for running container tests
  • verify: Sprawl of Python testing files (though listed as executables)

The Tools Directory

The tools directory largely contains configuration files for Travis, makefiles, and .supp files which also appear to be a kind of configuration file.

The Po Directory

This directory contains language files, which translate labels and other messages presented in the Cockpit interface.

The Pkg Directory

NPM's package directory

The Node Modules Directory

Used "For included Javascript libraries, and build processes".

The Examples Directory

The examples directory seems to be there to support testing. All subdirectories contain a mix of HTML files and Javascript source. Their specific purpose is not known

The Doc Directory

This contains markdown files and supporting content for the documentation

The Containers Directory

Contains configuration file for container managers, such as Kubernetes. Also contains testing files for what is presumed to be CI.

The Bots Directory

The Bots directory mainly contains executable scripts (Python files) for "automated bots and tools that work on Cockpit". OS image updates, changes to testing, and more. These are run automatically on pull-requests. Used by the authors with Github for continuous integration support.

Files of Interest

A large majority of the source content is plumbing and other infrastructural code for critical low-level functions. However, there remain some files that may be of special interest for modifying or applying changes to Cockpit. These are enumerated below:

  • src/base1/cockpit.js: All javascript functionality made available to the user by the webserver
  • src/base1/cockpit.css: Style sheets for adjusting the appearance of Cockpit
  • src/bridge/cockpitinternalmetrics.c: A Cockpit channel that pulls metric data from internal sources (CPU usage, memory usage, network interface, etc)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment