README
¶
Monogon Monorepo
This is the main repository containing the source code for the Monogon Platform.
This is pre-release software - take a look, and check back later! In the meantime, join us on Matrix (#monogon-os-community:matrix.org) or Discord.
Environment
Our build environment is self-contained and requires only minimal host dependencies:
- A Linux machine or VM.
- Bazelisk >= v1.15.0 (or a working Nix environment).
- A reasonably recent kernel with user namespaces enabled.
- Working KVM with access to
/dev/kvm(if you want to run tests).
Our docs assume that Bazelisk is available as bazel on your PATH.
Refer to SETUP.md for detailed instructions.
Monogon OS
The source code lives in //metropolis (Metropolis is the codename of Monogon OS).
See the //metropolis/README.md for a developer quick start guide, or see
the Monogon OS Handbook for user documentation.
Directories
¶
| Path | Synopsis |
|---|---|
|
build
|
|
|
analysis/importsort
importsort implements import grouping style checks as per CODING_STANDARDS.md.
|
importsort implements import grouping style checks as per CODING_STANDARDS.md. |
|
analysis/lib/genstd
This tool generates //build/analysis/lib:stdlib_packages.go, which contains a set of all Go stdlib packges.
|
This tool generates //build/analysis/lib:stdlib_packages.go, which contains a set of all Go stdlib packges. |
|
analysis/noioutil
Package noioutil contains a Go analysis pass designed to prevent use of the deprecated ioutil package for which a tree-wide migration was already done.
|
Package noioutil contains a Go analysis pass designed to prevent use of the deprecated ioutil package for which a tree-wide migration was already done. |
|
bazel_cc_fix
bazel_cc_fix rewrites include directives in C and C++ code.
|
bazel_cc_fix rewrites include directives in C and C++ code. |
|
toolbase
toolbase implements common functionality for tools operating on a Monogon workspace, notably CI and developer tools.
|
toolbase implements common functionality for tools operating on a Monogon workspace, notably CI and developer tools. |
|
cloud
|
|
|
bmaas/bmdb
Package bmdb implements a connector to the Bare Metal Database, which is the main data store backing information about bare metal machines.
|
Package bmdb implements a connector to the Bare Metal Database, which is the main data store backing information about bare metal machines. |
|
bmaas/bmdb/metrics
Package metrics implements a Prometheus metrics submission interface for BMDB client components.
|
Package metrics implements a Prometheus metrics submission interface for BMDB client components. |
|
bmaas/bmdb/reflection
Package reflection implements facilities to retrieve information about the implemented Tags and their types from a plain CockroachDB SQL connection, bypassing the queries/types defined in models.
|
Package reflection implements facilities to retrieve information about the implemented Tags and their types from a plain CockroachDB SQL connection, bypassing the queries/types defined in models. |
|
bmaas/bmdb/webug
Package webug implements a web-based debug/troubleshooting/introspection system for the BMDB.
|
Package webug implements a web-based debug/troubleshooting/introspection system for the BMDB. |
|
bmaas/scruffy
Package scruffy implements Scruffy, The Janitor.
|
Package scruffy implements Scruffy, The Janitor. |
|
equinix/wrapngo
Package wrapngo wraps packngo methods providing the following usability enhancements: - API call rate limiting - resource-aware call retries - use of a configurable back-off algorithm implementation - context awareness
|
Package wrapngo wraps packngo methods providing the following usability enhancements: - API call rate limiting - resource-aware call retries - use of a configurable back-off algorithm implementation - context awareness |
|
lib/component
Package component implements reusable bits for cloud service components.
|
Package component implements reusable bits for cloud service components. |
|
lib/sinbin
Package sinbin implements a sinbin for naughty processed elements that we wish to time out for a while.
|
Package sinbin implements a sinbin for naughty processed elements that we wish to time out for a while. |
|
shepherd/manager
Package manager, itself a part of BMaaS project, provides implementation governing Equinix bare metal server lifecycle according to conditions set by Bare Metal Database (BMDB).
|
Package manager, itself a part of BMaaS project, provides implementation governing Equinix bare metal server lifecycle according to conditions set by Bare Metal Database (BMDB). |
|
shepherd/manager/test_agent
test_agent is used by the Equinix Metal Manager test code.
|
test_agent is used by the Equinix Metal Manager test code. |
|
go
|
|
|
clitable
Package clitable implements tabular display for command line tools.
|
Package clitable implements tabular display for command line tools. |
|
mflags
Package mflags implements custom flags for use in monogon projects.
|
Package mflags implements custom flags for use in monogon projects. |
|
net/psample
Package psample provides a receiver for sampled network packets using the Netlink psample interface.
|
Package psample provides a receiver for sampled network packets using the Netlink psample interface. |
|
net/tinylb
Package tinylb implements a small and simple userland round-robin load balancer, mostly for TCP connections.
|
Package tinylb implements a small and simple userland round-robin load balancer, mostly for TCP connections. |
|
qcow2
Package qcow2 implements generating QEMU copy-on-write image files.
|
Package qcow2 implements generating QEMU copy-on-write image files. |
|
intellij
|
|
|
localconfig
localconfig modifies the project's IntelliJ config to include project-specific settings.
|
localconfig modifies the project's IntelliJ config to include project-specific settings. |
|
metropolis
|
|
|
cli/flagdefs
Package flagdefs contains shared flag definitions for Metropolis.
|
Package flagdefs contains shared flag definitions for Metropolis. |
|
cli/metroctl/core
Package core contains parts of metroctl which do significant amounts of work beyond just providing a CLI for them.
|
Package core contains parts of metroctl which do significant amounts of work beyond just providing a CLI for them. |
|
installer
Installer creates a Metropolis image at a suitable block device based on the installer bundle present in the installation medium's ESP, after which it reboots.
|
Installer creates a Metropolis image at a suitable block device based on the installer bundle present in the installation medium's ESP, after which it reboots. |
|
installer/test/testos
TestOS is a tiny "operating system" which is packaged the exact same way as an actual Metropolis node but only outputs a single flag before exiting.
|
TestOS is a tiny "operating system" which is packaged the exact same way as an actual Metropolis node but only outputs a single flag before exiting. |
|
node/core
This uses the unstable overrideWrite interface to also emit all runtime writes to a dedicated runtime file descriptor to catch and debug crash dumps.
|
This uses the unstable overrideWrite interface to also emit all runtime writes to a dedicated runtime file descriptor to catch and debug crash dumps. |
|
node/core/cluster
Package cluster implements low-level clustering logic, especially logic regarding to bootstrapping, registering into and joining a cluster.
|
Package cluster implements low-level clustering logic, especially logic regarding to bootstrapping, registering into and joining a cluster. |
|
node/core/clusternet
Package clusternet implements a Cluster Networking mesh service running on all Metropolis nodes.
|
Package clusternet implements a Cluster Networking mesh service running on all Metropolis nodes. |
|
node/core/consensus/client
package client implements a higher-level client for consensus/etcd that is to be used within the Metropolis node code for unprivileged access (ie.
|
package client implements a higher-level client for consensus/etcd that is to be used within the Metropolis node code for unprivileged access (ie. |
|
node/core/curator
package curator implements the Curator, a service responsible for management of the Metropolis cluster that it is running on.
|
package curator implements the Curator, a service responsible for management of the Metropolis cluster that it is running on. |
|
node/core/devmgr
Package devmgr is the userspace pendant to the kernel device management system.
|
Package devmgr is the userspace pendant to the kernel device management system. |
|
node/core/metrics/fake_exporter
fake_exporter is a tiny Prometheus-compatible metrics exporter which exports a single metric with a value configured at startup.
|
fake_exporter is a tiny Prometheus-compatible metrics exporter which exports a single metric with a value configured at startup. |
|
node/core/mgmt
Package mgmt implements the node-local management service, a.k.a.
|
Package mgmt implements the node-local management service, a.k.a. |
|
node/core/network/dhcp4c
Package dhcp4c implements a DHCPv4 Client as specified in RFC2131 (with some notable deviations).
|
Package dhcp4c implements a DHCPv4 Client as specified in RFC2131 (with some notable deviations). |
|
node/core/network/dhcp4c/callback
Package callback contains minimal callbacks for configuring the kernel with options received over DHCP.
|
Package callback contains minimal callbacks for configuring the kernel with options received over DHCP. |
|
node/core/network/dhcp4c/transport
Package transport contains Linux-based transports for the DHCP broadcast and unicast specifications.
|
Package transport contains Linux-based transports for the DHCP broadcast and unicast specifications. |
|
node/core/network/hostsfile
Package hostsfile implements a service which owns and writes all node-local files/interfaces used by the system to resolve the local node's name and the names of other nodes in the cluster:
|
Package hostsfile implements a service which owns and writes all node-local files/interfaces used by the system to resolve the local node's name and the names of other nodes in the cluster: |
|
node/core/roleserve
Package roleserve implements the roleserver/“Role Server”.
|
Package roleserve implements the roleserver/“Role Server”. |
|
node/core/time
Package time implements a supervisor runnable which is responsible for keeping both the system clock and the RTC accurate.
|
Package time implements a supervisor runnable which is responsible for keeping both the system clock and the RTC accurate. |
|
node/kubernetes/authproxy
Package authproxy implements an authenticating proxy in front of the K8s API server converting Metropolis credentials into authentication headers.
|
Package authproxy implements an authenticating proxy in front of the K8s API server converting Metropolis credentials into authentication headers. |
|
node/kubernetes/clusternet
Package clusternet implements a WireGuard-based overlay network for Kubernetes.
|
Package clusternet implements a WireGuard-based overlay network for Kubernetes. |
|
node/kubernetes/hyperkube
This is the entry point for our multicall Kubernetes binary.
|
This is the entry point for our multicall Kubernetes binary. |
|
node/kubernetes/metricsproxy
Package metricsproxy implements an authenticating proxy in front of the K8s controller-manager and scheduler providing unauthenticated access to the metrics via local ports
|
Package metricsproxy implements an authenticating proxy in front of the K8s controller-manager and scheduler providing unauthenticated access to the metrics via local ports |
|
node/kubernetes/nfproxy
Package nfproxy is a Kubernetes Service IP proxy based exclusively on the Linux nftables interface.
|
Package nfproxy is a Kubernetes Service IP proxy based exclusively on the Linux nftables interface. |
|
node/kubernetes/pki
package pki builds upon osbase/pki/ to provide an etcd-backed implementation of all x509 PKI Certificates/CAs required to run Kubernetes.
|
package pki builds upon osbase/pki/ to provide an etcd-backed implementation of all x509 PKI Certificates/CAs required to run Kubernetes. |
|
node/kubernetes/plugins/kvmdevice
Package kvmdevice implements a Kubernetes device plugin for the virtual KVM device.
|
Package kvmdevice implements a Kubernetes device plugin for the virtual KVM device. |
|
node/kubernetes/reconciler
The reconciler ensures that a base set of K8s resources is always available in the cluster.
|
The reconciler ensures that a base set of K8s resources is always available in the cluster. |
|
test/e2e/httpserver
httpserver serves a test HTTP endpoint for E2E testing.
|
httpserver serves a test HTTP endpoint for E2E testing. |
|
test/e2e/k8s_cts
This package launches a Metropolis cluster with two nodes and spawns in the CTS container.
|
This package launches a Metropolis cluster with two nodes and spawns in the CTS container. |
|
test/launch
cluster builds on the launch package and implements launching Metropolis nodes and clusters in a virtualized environment using qemu.
|
cluster builds on the launch package and implements launching Metropolis nodes and clusters in a virtualized environment using qemu. |
|
test/localregistry
Package localregistry implements a read-only OCI Distribution / Docker V2 container image registry backed by local layers.
|
Package localregistry implements a read-only OCI Distribution / Docker V2 container image registry backed by local layers. |
|
test/nanoswitch
nanoswitch is a virtualized switch/router combo intended for testing.
|
nanoswitch is a virtualized switch/router combo intended for testing. |
|
test/util
This file implements test helper functions that augment the way any given test is run.
|
This file implements test helper functions that augment the way any given test is run. |
|
vm/smoketest
This is a small smoke test which will run in a container on top of Metropolis Kubernetes.
|
This is a small smoke test which will run in a container on top of Metropolis Kubernetes. |
|
osbase
|
|
|
bootparam
Package bootparam implements encoding and decoding of Linux kernel command lines as documented in https://docs.kernel.org/admin-guide/kernel-parameters.html
|
Package bootparam implements encoding and decoding of Linux kernel command lines as documented in https://docs.kernel.org/admin-guide/kernel-parameters.html |
|
bootparam/ref
Package ref provides the reference implementation for kernel command line parsing as present in the Linux kernel.
|
Package ref provides the reference implementation for kernel command line parsing as present in the Linux kernel. |
|
bringup
Package bringup implements a simple wrapper which configures all default mounts, logging and the corresponding forwarders to tty0 and ttyS0.
|
Package bringup implements a simple wrapper which configures all default mounts, logging and the corresponding forwarders to tty0 and ttyS0. |
|
build/fwprune
fwprune is a buildsystem utility that filters linux-firmware repository contents to include only files required by the built-in kernel modules, that are specified in modules.builtin.modinfo.
|
fwprune is a buildsystem utility that filters linux-firmware repository contents to include only files required by the built-in kernel modules, that are specified in modules.builtin.modinfo. |
|
build/genosrelease
genosrelease provides rudimentary support to generate os-release files following the freedesktop spec from arguments and stamping
|
genosrelease provides rudimentary support to generate os-release files following the freedesktop spec from arguments and stamping |
|
build/mkerofs
mkerofs takes a specification in the form of a prototext file (see fsspec next to this) and assembles an EROFS filesystem according to it.
|
mkerofs takes a specification in the form of a prototext file (see fsspec next to this) and assembles an EROFS filesystem according to it. |
|
build/mkimage
mkimage is a tool to generate node disk images.
|
mkimage is a tool to generate node disk images. |
|
build/mkimage/osimage
This package provides self-contained implementation used to generate Metropolis disk images.
|
This package provides self-contained implementation used to generate Metropolis disk images. |
|
build/mkpayload
mkpayload is an objcopy wrapper that builds EFI unified kernel images.
|
mkpayload is an objcopy wrapper that builds EFI unified kernel images. |
|
build/mkucode
This assembles standalone microcode files into the format expected by the Linux microcode loader.
|
This assembles standalone microcode files into the format expected by the Linux microcode loader. |
|
build/mkverity
This package implements a command line tool that creates dm-verity hash images at a selected path, given an existing data image.
|
This package implements a command line tool that creates dm-verity hash images at a selected path, given an existing data image. |
|
cmd
Package cmd contains helpers that abstract away the chore of starting new processes, tracking their lifetime, inspecting their output, etc.
|
Package cmd contains helpers that abstract away the chore of starting new processes, tracking their lifetime, inspecting their output, etc. |
|
devicemapper
package devicemapper is a thin wrapper for the devicemapper ioctl API.
|
package devicemapper is a thin wrapper for the devicemapper ioctl API. |
|
efivarfs
Package efivarfs provides functions to read and manipulate UEFI runtime variables.
|
Package efivarfs provides functions to read and manipulate UEFI runtime variables. |
|
event
Package event defines and implements Event Values, a mechanism in which multiple consumers can watch a value for updates in a reliable way.
|
Package event defines and implements Event Values, a mechanism in which multiple consumers can watch a value for updates in a reliable way. |
|
fat32
Package fat32 implements a writer for the FAT32 filesystem.
|
Package fat32 implements a writer for the FAT32 filesystem. |
|
fsquota
Package fsquota provides a simplified interface to interact with Linux's filesystem qouta API.
|
Package fsquota provides a simplified interface to interact with Linux's filesystem qouta API. |
|
fsquota/quotactl
Package quotactl implements a low-level wrapper around the modern portion of Linux's quotactl() syscall.
|
Package quotactl implements a low-level wrapper around the modern portion of Linux's quotactl() syscall. |
|
gpt
Package gpt implements reading and writing GUID Partition Tables as specified in the UEFI Specification.
|
Package gpt implements reading and writing GUID Partition Tables as specified in the UEFI Specification. |
|
jsonpatch
Package jsonpatch contains data structures and encoders for JSON Patch (RFC 6902) and JSON Pointers (RFC 6901)
|
Package jsonpatch contains data structures and encoders for JSON Patch (RFC 6902) and JSON Pointers (RFC 6901) |
|
kexec
Package kexec allows executing subsequent kernels from Linux userspace.
|
Package kexec allows executing subsequent kernels from Linux userspace. |
|
logbuffer
Package logbuffer implements a fixed-size in-memory ring buffer for line-separated logs.
|
Package logbuffer implements a fixed-size in-memory ring buffer for line-separated logs. |
|
logtree
Package logtree implements a tree-shaped logger for debug events.
|
Package logtree implements a tree-shaped logger for debug events. |
|
logtree/unraw
Package unraw implements a facility to convert raw logs from external sources into leveled logs.
|
Package unraw implements a facility to convert raw logs from external sources into leveled logs. |
|
loop
Package loop implements an interface to configure Linux loop devices.
|
Package loop implements an interface to configure Linux loop devices. |
|
msguid
Package msguid provides functions to convert UUIDs/GUIDs to and from Microsoft's idiosyncratic "mixed-endian" format.
|
Package msguid provides functions to convert UUIDs/GUIDs to and from Microsoft's idiosyncratic "mixed-endian" format. |
|
net/dns
Package dns provides a DNS server for resolving services against.
|
Package dns provides a DNS server for resolving services against. |
|
net/dns/forward
Package forward implements a forwarding proxy.
|
Package forward implements a forwarding proxy. |
|
net/dns/forward/cache
Package cache implements a cache.
|
Package cache implements a cache. |
|
net/dns/forward/proxy
Package proxy implements a forwarding proxy.
|
Package proxy implements a forwarding proxy. |
|
net/dns/forward/up
Package up is used to run a function for some duration.
|
Package up is used to run a function for some duration. |
|
net/dns/kubernetes
Package kubernetes provides the kubernetes backend.
|
Package kubernetes provides the kubernetes backend. |
|
net/dns/kubernetes/object
Package object holds functions that convert the objects from the k8s API in to a more memory efficient structures.
|
Package object holds functions that convert the objects from the k8s API in to a more memory efficient structures. |
|
nvme
Package nvme provides methods and data structures for issuing commands to device speaking the NVMe protocol.
|
Package nvme provides methods and data structures for issuing commands to device speaking the NVMe protocol. |
|
pki
package pki implements an x509 PKI (Public Key Infrastructure) system backed on etcd.
|
package pki implements an x509 PKI (Public Key Infrastructure) system backed on etcd. |
|
pstore
The pstore package provides functions for interfacing with the Linux kernel's pstore (persistent storage) system.
|
The pstore package provides functions for interfacing with the Linux kernel's pstore (persistent storage) system. |
|
scsi
INCITS 502 Revision 19 / SPC-5 R19
|
INCITS 502 Revision 19 / SPC-5 R19 |
|
smbios
Package smbios implements parsing of SMBIOS data structures.
|
Package smbios implements parsing of SMBIOS data structures. |
|
socksproxy
Package socksproxy implements a limited subset of the SOCKS 5 (RFC1928) protocol in the form of a pluggable Proxy object.
|
Package socksproxy implements a limited subset of the SOCKS 5 (RFC1928) protocol in the form of a pluggable Proxy object. |
|
sysfs
Implementation included in this file was written with the aim of easing integration with the interface exposed at /sys/class/block.
|
Implementation included in this file was written with the aim of easing integration with the interface exposed at /sys/class/block. |
|
test/ktest
ktest is a test launcher for running tests inside a custom kernel and passes the results back out.
|
ktest is a test launcher for running tests inside a custom kernel and passes the results back out. |
|
test/ktest/init
ktestinit is an init designed to run inside a lightweight VM for running tests in there.
|
ktestinit is an init designed to run inside a lightweight VM for running tests in there. |
|
test/launch
launch implements test harnesses for running qemu VMs from tests.
|
launch implements test harnesses for running qemu VMs from tests. |
|
tpm/eventlog
Taken and pruned from go-attestation under Apache 2.0
|
Taken and pruned from go-attestation under Apache 2.0 |
|
tpm/eventlog/internal
Taken from go-attestation under Apache 2.0
|
Taken from go-attestation under Apache 2.0 |
|
verity
This package implements the minimum of functionality needed to generate and map dm-verity images.
|
This package implements the minimum of functionality needed to generate and map dm-verity images. |
|
watchdog
Package watchdog provides access to hardware watchdogs.
|
Package watchdog provides access to hardware watchdogs. |
|
third_party
|
|
|
Package version is a companion library to the //version/spec proto.
|
Package version is a companion library to the //version/spec proto. |
|
stampgo
Package main implements 'stampgo', a tool to convert build status data into a version.spec.Version proto, which is then embedded into a Go source file.
|
Package main implements 'stampgo', a tool to convert build status data into a version.spec.Version proto, which is then embedded into a Go source file. |
Click to show internal directories.
Click to hide internal directories.