Config kinds¶
This page is for operators who write a node's config documents, an inventory or a lab file. It
lists the config kinds that an image with the Kubernetes layer accepts, and those a router
image adds, by API group, and the fields of the inventory and the lab file that chalkctl and
chalklab read. An image whose modules declare kinds of their own under
chalkos.kinds accepts those as well.
Every document has an apiVersion, a kind, a metadata.name of lower-case letters, digits,
- and ., and a spec, whose fields the tables list. A field within another is listed by its
whole path, where <name> stands for each key of a map and [] for each item of a list:
spec.vip.addresses is the field addresses of the object spec.vip. An object has a row of
its own only when it has a description, may be null or must be set; an object a document leaves
out takes the defaults of its fields. A default that reads "required" means the field must be
set, and — means it has no default. A field the tables do not list is refused, except within a
Kubernetes object or an object whose type reads "object, any fields".
chalkos.dev¶
The kinds of chalkos.dev set the node's host name and hold the secrets that other documents name.
Host¶
The host name the node sets at boot.
apiVersion: chalkos.dev/v1alpha1
A node's config holds at most one.
| Field | Type | Default | Description |
|---|---|---|---|
spec.hostname |
string or null | null |
Host name set at boot; null takes the node's name in the inventory. |
Secret¶
Secret values that other documents name by reference, such as a Registry's password.
apiVersion: chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own.
| Field | Type | Default | Description |
|---|---|---|---|
spec.data |
map of string | required | Secret values by key, which secretRef fields of other documents name. |
kubernetes.chalkos.dev¶
The kinds of kubernetes.chalkos.dev set up the Kubernetes cluster and the node's part in it. Only images that run Kubernetes accept them, and Flannel only those whose CNI is flannel.
Addon¶
Kubernetes objects that the control planes apply to the cluster.
apiVersion: kubernetes.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. The kind is withheld: no service reads its documents, and chalkcfg prints none.
| Field | Type | Default | Description |
|---|---|---|---|
spec.objects |
list of Kubernetes object | required | Kubernetes objects the control planes apply with server-side apply after chalkos's own, in this order; the objects of several Addon documents in the order of their names. chalkctl delivers them to control planes alone, and a worker applies none. |
BGPPeer¶
A BGP neighbour of the node: its AS number, the address or interfaces of its sessions, their password and BFD, and the routes the node takes from it.
apiVersion: kubernetes.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 9 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.address |
IP address or null | null |
Unicast address of the neighbour, IPv4 or IPv6, neither loopback nor link-local, on a subnet of an interface of the node: eBGP runs with a TTL of 1, so the neighbour is on a link the node is connected to. One session to it, or bound to the one interface of interfaces. Null for unnumbered sessions on interfaces. A session to an IPv4 address carries IPv4 routes alone, and one to an IPv6 address without an interface IPv6 routes alone; bound to an interface, a session to an IPv6 address carries both, IPv4 routes with IPv6 next hops. Unique among the BGPPeer documents, compared as addresses. |
spec.asn |
integer from 1 to 4294967295 | required | AS number of the neighbour. |
spec.bfd |
boolean | true |
Whether BFD watches each session, so that FRR ends it within about a second of its link failing. |
spec.import |
one of default, none |
"default" |
Routes the node takes from the neighbour: default its default routes, 0.0.0.0/0 and ::/0, alone; none nothing. zebra installs a default route from BGP only while the node has no other, such as one from a router advertisement. |
spec.interfaces |
list of string or null | null |
Interfaces of the sessions, each named by a Network document's [Match] Name=. Without address, an unnumbered session on each, to the neighbour's IPv6 link-local address, which carries IPv4 and IPv6 routes; with address, the one interface its session is bound to. FRR sends router advertisements on these interfaces, which find the neighbour of an unnumbered session, with a router lifetime of 0, so no host on the link takes the node as its default router. Each item is unique within the list. |
spec.password |
secret reference or null | null |
Key of a Secret that holds the sessions' TCP MD5 password, of 1 to 80 printable characters without white space; null for none. The Secret's name and key hold letters, digits, ., _ and - alone. |
BGPSpeaker¶
The node's side of its BGP sessions: its AS number, its router ID and the interfaces whose addresses FRR announces to every BGPPeer.
apiVersion: kubernetes.chalkos.dev/v1alpha1
A node's config holds at most one. It has 4 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.asn |
integer from 1 to 4294967295 | required | AS number of the node. It stays while the node holds a BGPSpeaker; a new one takes a delivery without the BGPSpeaker first. |
spec.export |
object | required | What FRR announces to every BGPPeer: the routes the node originates. FRR passes on no route it learns from a peer, so the node is no transit. |
spec.export.interfaces |
list of string | required | Interfaces whose addresses FRR announces, each named by a Network document's [Match] Name=: an address of /32 or /128 as itself, another as its subnet. The VIP is announced while the node holds it on one of them, its Node's vip.interface. Each item is unique within the list. |
spec.routerID |
string or null | null |
Router ID in the form of an IPv4 address other than 0.0.0.0, unique within the node's AS; null takes the first IPv4 address of the Node's nodeIP.addresses, which a node without one cannot. |
Cluster¶
The Kubernetes cluster the node belongs to: its API server's endpoint, its address families and ranges, its VIP, the images of its components and the flags of its control-plane components.
apiVersion: kubernetes.chalkos.dev/v1alpha1
A node's config holds at most one. It has 5 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.allowSchedulingOnControlPlanes |
boolean | false |
Whether workloads run on control-plane nodes, which otherwise register with the taint node-role.kubernetes.io/control-plane:NoSchedule; it is fixed once the node holds a Kubernetes share. |
spec.dnsIPs.ipv4 |
IP address or null | null |
Service address of the cluster DNS in the family's service range; null is its 10th address. Pods use the primary family's. |
spec.dnsIPs.ipv6 |
IP address or null | null |
Service address of the cluster DNS in the family's service range; null is its 10th address. Pods use the primary family's. |
spec.domain |
string | "cluster.local" |
DNS domain of the cluster. |
spec.endpoint |
string | required | URL of the cluster's Kubernetes API server, which every node of the cluster names alike. |
spec.extraArgs.etcd |
map of string | {} |
Extra flags of etcd, named without the leading dashes with letters, digits, _, . and -, starting with a letter or digit; they override chalkos's own, except the flags chalkos protects, which are refused. |
spec.extraArgs.kube-apiserver |
map of string | {} |
Extra flags of the API server, named without the leading dashes with letters, digits, _, . and -, starting with a letter or digit; they override chalkos's own, except the flags chalkos protects, which are refused. |
spec.extraArgs.kube-controller-manager |
map of string | {} |
Extra flags of the controller-manager, named without the leading dashes with letters, digits, _, . and -, starting with a letter or digit; they override chalkos's own, except the flags chalkos protects, which are refused. |
spec.extraArgs.kube-scheduler |
map of string | {} |
Extra flags of the scheduler, named without the leading dashes with letters, digits, _, . and -, starting with a letter or digit; they override chalkos's own, except the flags chalkos protects, which are refused. |
spec.images |
object | required | |
spec.images.apiServer |
image reference with a version tag | required | Image of the API server. containerd pulls it as written: a registry, a repository and a tag, a digest or both. Written as repository:tag@sha256:<digest>, it is pulled by its digest. Its tag is its Kubernetes version, v<major>.<minor>.<patch> with an optional suffix such as -rc.1, which the image's checker compares with the kubelet's and the other components' by Kubernetes's version skew policy. |
spec.images.controllerManager |
image reference with a version tag | required | Image of the controller-manager. containerd pulls it as written: a registry, a repository and a tag, a digest or both. Written as repository:tag@sha256:<digest>, it is pulled by its digest. Its tag is its Kubernetes version, v<major>.<minor>.<patch> with an optional suffix such as -rc.1, which the image's checker compares with the kubelet's and the other components' by Kubernetes's version skew policy. |
spec.images.coredns |
image reference | required | Image of CoreDNS, the cluster DNS. containerd pulls it as written: a registry, a repository and a tag, a digest or both. Written as repository:tag@sha256:<digest>, it is pulled by its digest. |
spec.images.etcd |
image reference | required | Image of etcd, which control planes run. containerd pulls it as written: a registry, a repository and a tag, a digest or both. Written as repository:tag@sha256:<digest>, it is pulled by its digest. |
spec.images.flannel |
image reference | required | Image of flannel. containerd pulls it as written: a registry, a repository and a tag, a digest or both. Written as repository:tag@sha256:<digest>, it is pulled by its digest. An image whose CNI is flannel requires it, and an image with another CNI refuses it. |
spec.images.pause |
image reference | required | Image of the pod sandbox, which containerd runs for every pod. containerd pulls it as written: a registry, a repository and a tag, a digest or both. Written as repository:tag@sha256:<digest>, it is pulled by its digest. |
spec.images.proxy |
image reference with a version tag | required | Image of kube-proxy. containerd pulls it as written: a registry, a repository and a tag, a digest or both. Written as repository:tag@sha256:<digest>, it is pulled by its digest. Its tag is its Kubernetes version, v<major>.<minor>.<patch> with an optional suffix such as -rc.1, which the image's checker compares with the kubelet's and the other components' by Kubernetes's version skew policy. |
spec.images.scheduler |
image reference with a version tag | required | Image of the scheduler. containerd pulls it as written: a registry, a repository and a tag, a digest or both. Written as repository:tag@sha256:<digest>, it is pulled by its digest. Its tag is its Kubernetes version, v<major>.<minor>.<patch> with an optional suffix such as -rc.1, which the image's checker compares with the kubelet's and the other components' by Kubernetes's version skew policy. |
spec.ipFamilies |
list of one of ipv4, ipv6 |
["ipv4"] |
Address families of the cluster, the primary one first, each once. They are fixed when the cluster is created. Each item is unique within the list. |
spec.nodeCIDRMaskSizes.ipv4 |
integer from 1 to 128 | 24 |
Prefix length of each node's part of the family's pod range. |
spec.nodeCIDRMaskSizes.ipv6 |
integer from 1 to 128 | 64 |
Prefix length of each node's part of the family's pod range. |
spec.nodeIP.timeout |
integer of at least 1 | 300 |
Seconds a node waits at boot for its address. |
spec.nodeIP.validSubnets |
list of string | [] |
Subnets in CIDR notation that nodes without a fixed address pick theirs from at boot, unless a Node gives its own; a leading ! excludes one. Empty takes any global unicast address. |
spec.podCIDRs.ipv4 |
address range | "10.244.0.0/16" |
Address range of the family's pods; each node gets a part of it. |
spec.podCIDRs.ipv6 |
address range | "fd00:10:244::/56" |
Address range of the family's pods; each node gets a part of it. |
spec.serviceCIDRs.ipv4 |
address range | "10.96.0.0/12" |
Address range of the family's services, at most 2^20 addresses. |
spec.serviceCIDRs.ipv6 |
address range | "fd00:10:96::/112" |
Address range of the family's services, at most 2^20 addresses. |
spec.vip.addresses |
list of IP address | [] |
Virtual addresses of the API server, at most one per family; empty means no virtual IP. |
spec.vip.mode |
one of l2, routed |
"l2" |
Way the node holding the VIP makes its addresses reachable: l2 adds them to an interface and announces them to the neighbours with gratuitous ARP and unsolicited neighbour advertisements; routed adds them to an interface as host addresses, /32 or /128, and announces nothing, so a routing daemon on the node announces them. In routed, every control plane names its vip.interface. |
ClusterRegistry¶
The cluster registry: chalkos-registry on the nodes whose static addresses its endpoints name, every control plane among them. containerd on every node pulls the images of the mirrored hosts from it first, before their Mirror endpoints and the hosts themselves.
apiVersion: kubernetes.chalkos.dev/v1alpha1
A node's config holds at most one. It has a change rule.
| Field | Type | Default | Description |
|---|---|---|---|
spec.endpoints |
list of IP address | required | IP addresses of the nodes that serve the cluster registry, in the order nodes pull from them; a node that serves it pulls from itself first. A node serves it when one of these is one of its static addresses, the Address= values of its Network documents, and every control plane serves it. chalkctl registry push pushes to each, and nothing copies images between them. Each item is unique within the list, compared as addresses. |
spec.mirrors |
list of string | required | Registry hosts whose images containerd pulls from the cluster registry first, as image references name them, without a port; docker.io is Docker Hub. The cluster registry holds an image below its host's name, in lower case: docker.io/library/nginx is <endpoint>/docker.io/library/nginx. Each item is unique within the list, compared as registry hosts. |
spec.port |
integer from 1024 to 65535 | 5000 |
TCP port the cluster registry serves on, over HTTPS with the node certificate: 1024 or above, as chalkos-registry runs without privileges. |
Flannel¶
The settings of flannel, the cluster's CNI, for the VXLAN between the nodes.
apiVersion: kubernetes.chalkos.dev/v1alpha1
A node's config holds at most one.
| Field | Type | Default | Description |
|---|---|---|---|
spec.mtu |
integer of at least 1 or null | null |
MTU flannel's VXLAN assumes for the network between the nodes; its VXLAN devices and the pods get 50 less. null takes the MTU of the interface holding the node's address. |
spec.vxlanSourceSubnets |
list of address range | [] |
Ranges flannel's VXLAN must come from, one of each family at least; empty takes VXLAN from any source. |
Node¶
The node's part in the Kubernetes cluster: its type, the labels and taints it registers with, its address, the interface of the VIP and its kubelet's flags.
apiVersion: kubernetes.chalkos.dev/v1alpha1
A node's config holds at most one. It has 4 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.kubeletExtraArgs |
map of string | {} |
Extra flags of the kubelet, named without the leading dashes with letters, digits, _, . and -, starting with a letter or digit; they override chalkos's own, except the flags chalkos protects, which are refused. |
spec.labels |
map of string | {} |
Kubernetes labels the node registers with; they are fixed once the node holds a Kubernetes share. |
spec.nodeIP.addresses |
list of IP address or null | null |
Fixed addresses of the node, at most one per family; null takes the first static address of each family unless validSubnets apply. |
spec.nodeIP.validSubnets |
list of string or null | null |
Subnets the node picks its address from, which replace the Cluster's nodeIP.validSubnets as a whole; null takes the Cluster's. |
spec.taints |
list of object | [] |
Kubernetes taints the node registers with; they are fixed once the node holds a Kubernetes share. |
spec.taints[].effect |
one of NoSchedule, PreferNoSchedule, NoExecute |
required | Effect of the taint on pods that do not tolerate it. |
spec.taints[].key |
string | required | Taint key. |
spec.taints[].value |
string or null | null |
Taint value; null for a taint without a value. |
spec.type |
one of controlplane, worker |
required | Type of the node in the cluster; it is fixed once the node holds a Kubernetes share. |
spec.vip.interface |
string or null | null |
Interface the node adds the Cluster's VIP addresses to while it holds them; null means the one holding the node's address of their family, which a routed VIP does not allow. Only control planes hold the VIP, so a worker's stays null. |
networkd.chalkos.dev¶
The kinds of networkd.chalkos.dev are the .link, .netdev and .network files of the image's systemd as documents. Their schemas are generated from that systemd, so they accept the sections and keys it reads.
Link¶
A systemd .link file, which udev applies to the network devices it matches, such as to name them or set their offloads.
apiVersion: networkd.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own.
Each field of spec is a section of the unit: an object, or a list of objects for a
section written more than once. Each key of a section is networkd's key in camelCase and takes
a value, or a list for a key written more than once. The table gives each section and key as
networkd spells it.
| Field | networkd section | Keys |
|---|---|---|
spec.energyEfficientEthernet |
EnergyEfficientEthernet | enable (Enable), linkMode (LinkMode), txLowPowerIdle (TxLowPowerIdle), txLowPowerIdleSec (TxLowPowerIdleSec) |
spec.link |
Link | advertise (Advertise), alias (Alias), alternativeName (AlternativeName), alternativeNamesPolicy (AlternativeNamesPolicy), autoNegotiation (AutoNegotiation), autoNegotiationFlowControl (AutoNegotiationFlowControl), bitsPerSecond (BitsPerSecond), coalescePacketRateHigh (CoalescePacketRateHigh), coalescePacketRateLow (CoalescePacketRateLow), coalescePacketRateSampleIntervalSec (CoalescePacketRateSampleIntervalSec), combinedChannels (CombinedChannels), description (Description), duplex (Duplex), genericReceiveOffload (GenericReceiveOffload), genericReceiveOffloadHardware (GenericReceiveOffloadHardware), genericReceiveOffloadList (GenericReceiveOffloadList), genericReceiveOffloadUDPForwarding (GenericReceiveOffloadUDPForwarding), genericSegmentOffloadMaxBytes (GenericSegmentOffloadMaxBytes), genericSegmentOffloadMaxSegments (GenericSegmentOffloadMaxSegments), genericSegmentationOffload (GenericSegmentationOffload), importProperty (ImportProperty), irqAffinity (IRQAffinity), irqAffinityNUMA (IRQAffinityNUMA), irqAffinityPolicy (IRQAffinityPolicy), largeReceiveOffload (LargeReceiveOffload), macAddress (MACAddress), macAddressPolicy (MACAddressPolicy), mdi (MDI), mtuBytes (MTUBytes), nTupleFilter (NTupleFilter), name (Name), namePolicy (NamePolicy), otherChannels (OtherChannels), partialGenericSegmentationOffload (PartialGenericSegmentationOffload), port (Port), property (Property), receiveAll (ReceiveAll), receiveChecksumOffload (ReceiveChecksumOffload), receiveFCS (ReceiveFCS), receivePacketSteeringCPUMask (ReceivePacketSteeringCPUMask), receiveQueues (ReceiveQueues), receiveVLANCTAGFilter (ReceiveVLANCTAGFilter), receiveVLANCTAGHardwareAcceleration (ReceiveVLANCTAGHardwareAcceleration), rxBufferSize (RxBufferSize), rxChannels (RxChannels), rxCoalesceHighSec (RxCoalesceHighSec), rxCoalesceIrqSec (RxCoalesceIrqSec), rxCoalesceLowSec (RxCoalesceLowSec), rxCoalesceSec (RxCoalesceSec), rxFlowControl (RxFlowControl), rxJumboBufferSize (RxJumboBufferSize), rxMaxCoalescedFrames (RxMaxCoalescedFrames), rxMaxCoalescedHighFrames (RxMaxCoalescedHighFrames), rxMaxCoalescedIrqFrames (RxMaxCoalescedIrqFrames), rxMaxCoalescedLowFrames (RxMaxCoalescedLowFrames), rxMiniBufferSize (RxMiniBufferSize), scatterGather (ScatterGather), scatterGatherFragmentList (ScatterGatherFragmentList), sriovVirtualFunctions (SR-IOVVirtualFunctions), statisticsBlockCoalesceSec (StatisticsBlockCoalesceSec), tcp6SegmentationOffload (TCP6SegmentationOffload), tcpMangleIdSegmentationOffload (TCPMangleIdSegmentationOffload), tcpSegmentationOffload (TCPSegmentationOffload), tcpecnSegmentationOffload (TCPECNSegmentationOffload), transmitChecksumOffload (TransmitChecksumOffload), transmitQueueLength (TransmitQueueLength), transmitQueues (TransmitQueues), transmitVLANCTAGHardwareAcceleration (TransmitVLANCTAGHardwareAcceleration), transmitVLANSTAGHardwareAcceleration (TransmitVLANSTAGHardwareAcceleration), txBufferSize (TxBufferSize), txChannels (TxChannels), txCoalesceHighSec (TxCoalesceHighSec), txCoalesceIrqSec (TxCoalesceIrqSec), txCoalesceLowSec (TxCoalesceLowSec), txCoalesceSec (TxCoalesceSec), txFlowControl (TxFlowControl), txMaxCoalescedFrames (TxMaxCoalescedFrames), txMaxCoalescedHighFrames (TxMaxCoalescedHighFrames), txMaxCoalescedIrqFrames (TxMaxCoalescedIrqFrames), txMaxCoalescedLowFrames (TxMaxCoalescedLowFrames), udpSegmentationOffload (UDPSegmentationOffload), unsetProperty (UnsetProperty), useAdaptiveRxCoalesce (UseAdaptiveRxCoalesce), useAdaptiveTxCoalesce (UseAdaptiveTxCoalesce), wakeOnLan (WakeOnLan), wakeOnLanPassword (WakeOnLanPassword) |
spec.match |
Match | architecture (Architecture), credential (Credential), driver (Driver), firmware (Firmware), host (Host), kernelCommandLine (KernelCommandLine), kernelVersion (KernelVersion), kind (Kind), macAddress (MACAddress), machineTag (MachineTag), originalName (OriginalName), path (Path), permanentMACAddress (PermanentMACAddress), property (Property), type (Type), version (Version), virtualization (Virtualization) |
spec.sriov |
SR-IOV | linkState (LinkState), macAddress (MACAddress), macSpoofCheck (MACSpoofCheck), qualityOfService (QualityOfService), queryReceiveSideScaling (QueryReceiveSideScaling), trust (Trust), virtualFunction (VirtualFunction), vlanId (VLANId), vlanProtocol (VLANProtocol) |
NetDev¶
A systemd-networkd .netdev file, which creates a virtual network device, such as a VLAN, a bond or a bridge.
apiVersion: networkd.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own.
Each field of spec is a section of the unit: an object, or a list of objects for a
section written more than once. Each key of a section is networkd's key in camelCase and takes
a value, or a list for a key written more than once. The table gives each section and key as
networkd spells it.
| Field | networkd section | Keys |
|---|---|---|
spec.bareUDP |
BareUDP | destinationPort (DestinationPort), etherType (EtherType), minSourcePort (MinSourcePort) |
spec.batmanAdvanced |
BatmanAdvanced | aggregation (Aggregation), bridgeLoopAvoidance (BridgeLoopAvoidance), distributedArpTable (DistributedArpTable), fragmentation (Fragmentation), gatewayBandwidthDown (GatewayBandwidthDown), gatewayBandwidthUp (GatewayBandwidthUp), gatewayBandwithDown (GatewayBandwithDown), gatewayBandwithUp (GatewayBandwithUp), gatewayMode (GatewayMode), hopPenalty (HopPenalty), originatorIntervalSec (OriginatorIntervalSec), routingAlgorithm (RoutingAlgorithm) |
spec.bond |
Bond | adActorSystem (AdActorSystem), adActorSystemPriority (AdActorSystemPriority), adSelect (AdSelect), adUserPortKey (AdUserPortKey), allSlavesActive (AllSlavesActive), arpAllTargets (ARPAllTargets), arpIntervalSec (ARPIntervalSec), arpMissedMax (ARPMissedMax), arpValidate (ARPValidate), arpipTargets (ARPIPTargets), downDelaySec (DownDelaySec), dynamicTransmitLoadBalancing (DynamicTransmitLoadBalancing), failOverMACPolicy (FailOverMACPolicy), gratuitousARP (GratuitousARP), lacpTransmitRate (LACPTransmitRate), learnPacketIntervalSec (LearnPacketIntervalSec), miiMonitorSec (MIIMonitorSec), minLinks (MinLinks), mode (Mode), packetsPerSlave (PacketsPerSlave), peerNotifyDelaySec (PeerNotifyDelaySec), primaryReselectPolicy (PrimaryReselectPolicy), resendIGMP (ResendIGMP), transmitHashPolicy (TransmitHashPolicy), upDelaySec (UpDelaySec) |
spec.bridge |
Bridge | ageingTimeSec (AgeingTimeSec), defaultPVID (DefaultPVID), fdbMaxLearned (FDBMaxLearned), forwardDelaySec (ForwardDelaySec), groupForwardMask (GroupForwardMask), helloTimeSec (HelloTimeSec), linkLocalLearning (LinkLocalLearning), maxAgeSec (MaxAgeSec), multicastIGMPVersion (MulticastIGMPVersion), multicastQuerier (MulticastQuerier), multicastSnooping (MulticastSnooping), priority (Priority), stp (STP), vlanFiltering (VLANFiltering), vlanProtocol (VLANProtocol) |
spec.fooOverUDP |
FooOverUDP | encapsulation (Encapsulation), local (Local), peer (Peer), peerPort (PeerPort), port (Port), protocol (Protocol) |
spec.geneve |
GENEVE | destinationPort (DestinationPort), flowLabel (FlowLabel), id (Id), inheritInnerProtocol (InheritInnerProtocol), ipDoNotFragment (IPDoNotFragment), remote (Remote), tos (TOS), ttl (TTL), udp6ZeroCheckSumRx (UDP6ZeroCheckSumRx), udp6ZeroCheckSumTx (UDP6ZeroCheckSumTx), udp6ZeroChecksumRx (UDP6ZeroChecksumRx), udp6ZeroChecksumTx (UDP6ZeroChecksumTx), udpChecksum (UDPChecksum) |
spec.hsr |
HSR | ports (Ports), protocol (Protocol), supervision (Supervision) |
spec.ipoib |
IPoIB | ignoreUserspaceMulticastGroups (IgnoreUserspaceMulticastGroups), mode (Mode), partitionKey (PartitionKey) |
spec.ipvlan |
IPVLAN | flags (Flags), mode (Mode) |
spec.ipvtap |
IPVTAP | flags (Flags), mode (Mode) |
spec.l2tp |
L2TP | encapsulationType (EncapsulationType), local (Local), peerTunnelId (PeerTunnelId), remote (Remote), tunnelId (TunnelId), udp6CheckSumRx (UDP6CheckSumRx), udp6CheckSumTx (UDP6CheckSumTx), udp6ChecksumRx (UDP6ChecksumRx), udp6ChecksumTx (UDP6ChecksumTx), udpCheckSum (UDPCheckSum), udpChecksum (UDPChecksum), udpDestinationPort (UDPDestinationPort), udpSourcePort (UDPSourcePort) |
spec.l2tpSession |
L2TPSession | layer2SpecificHeader (Layer2SpecificHeader), name (Name), peerSessionId (PeerSessionId), sessionId (SessionId) |
spec.macsec |
MACsec | encrypt (Encrypt), port (Port) |
spec.macsecReceiveAssociation |
MACsecReceiveAssociation | activate (Activate), key (Key), keyFile (KeyFile), keyId (KeyId), macAddress (MACAddress), packetNumber (PacketNumber), port (Port) |
spec.macsecReceiveChannel |
MACsecReceiveChannel | macAddress (MACAddress), port (Port) |
spec.macsecTransmitAssociation |
MACsecTransmitAssociation | activate (Activate), key (Key), keyFile (KeyFile), keyId (KeyId), packetNumber (PacketNumber), useForEncoding (UseForEncoding) |
spec.macvlan |
MACVLAN | broadcastMulticastQueueLength (BroadcastMulticastQueueLength), broadcastQueueThreshold (BroadcastQueueThreshold), mode (Mode), sourceMACAddress (SourceMACAddress) |
spec.macvtap |
MACVTAP | mode (Mode), sourceMACAddress (SourceMACAddress) |
spec.match |
Match | architecture (Architecture), credential (Credential), firmware (Firmware), host (Host), kernelCommandLine (KernelCommandLine), kernelVersion (KernelVersion), machineTag (MachineTag), version (Version), virtualization (Virtualization) |
spec.netDev |
NetDev | description (Description), kind (Kind), macAddress (MACAddress), mtuBytes (MTUBytes), name (Name) |
spec.peer |
Peer | macAddress (MACAddress), name (Name) |
spec.tap |
Tap | group (Group), keepCarrier (KeepCarrier), multiQueue (MultiQueue), oneQueue (OneQueue), packetInfo (PacketInfo), user (User), vNetHeader (VNetHeader) |
spec.tun |
Tun | group (Group), keepCarrier (KeepCarrier), multiQueue (MultiQueue), oneQueue (OneQueue), packetInfo (PacketInfo), user (User), vNetHeader (VNetHeader) |
spec.tunnel |
Tunnel | allowLocalRemote (AllowLocalRemote), assignToLoopback (AssignToLoopback), copyDSCP (CopyDSCP), discoverPathMTU (DiscoverPathMTU), encapsulation (Encapsulation), encapsulationLimit (EncapsulationLimit), erspanDirection (ERSPANDirection), erspanHardwareId (ERSPANHardwareId), erspanIndex (ERSPANIndex), erspanVersion (ERSPANVersion), external (External), fooOverUDP (FooOverUDP), fouDestinationPort (FOUDestinationPort), fouSourcePort (FOUSourcePort), ignoreDontFragment (IgnoreDontFragment), independent (Independent), inputKey (InputKey), ipv6FlowLabel (IPv6FlowLabel), ipv6RapidDeploymentPrefix (IPv6RapidDeploymentPrefix), isatap (ISATAP), key (Key), local (Local), mode (Mode), outputKey (OutputKey), remote (Remote), serializeTunneledPackets (SerializeTunneledPackets), tos (TOS), ttl (TTL) |
spec.vlan |
VLAN | egressQOSMaps (EgressQOSMaps), gvrp (GVRP), id (Id), ingressQOSMaps (IngressQOSMaps), looseBinding (LooseBinding), mvrp (MVRP), protocol (Protocol), reorderHeader (ReorderHeader) |
spec.vrf |
VRF | table (Table), tableId (TableId) |
spec.vxcan |
VXCAN | peer (Peer) |
spec.vxlan |
VXLAN | arpProxy (ARPProxy), destinationPort (DestinationPort), external (External), fdbAgeingSec (FDBAgeingSec), flowLabel (FlowLabel), genericProtocolExtension (GenericProtocolExtension), group (Group), groupPolicyExtension (GroupPolicyExtension), id (Id), independent (Independent), ipDoNotFragment (IPDoNotFragment), l2MissNotification (L2MissNotification), l3MissNotification (L3MissNotification), local (Local), macLearning (MacLearning), maximumFDBEntries (MaximumFDBEntries), portRange (PortRange), reduceARPProxy (ReduceARPProxy), remote (Remote), remoteChecksumRx (RemoteChecksumRx), remoteChecksumTx (RemoteChecksumTx), routeShortCircuit (RouteShortCircuit), tos (TOS), ttl (TTL), udp6ZeroCheckSumRx (UDP6ZeroCheckSumRx), udp6ZeroCheckSumTx (UDP6ZeroCheckSumTx), udp6ZeroChecksumRx (UDP6ZeroChecksumRx), udp6ZeroChecksumTx (UDP6ZeroChecksumTx), udpCheckSum (UDPCheckSum), udpChecksum (UDPChecksum), vni (VNI), vniFilter (VNIFilter) |
spec.wireGuard |
WireGuard | firewallMark (FirewallMark), fwMark (FwMark), listenPort (ListenPort), privateKey (PrivateKey), privateKeyFile (PrivateKeyFile), routeMetric (RouteMetric), routeTable (RouteTable) |
spec.wireGuardPeer |
WireGuardPeer | allowedIPs (AllowedIPs), endpoint (Endpoint), persistentKeepalive (PersistentKeepalive), presharedKey (PresharedKey), presharedKeyFile (PresharedKeyFile), publicKey (PublicKey), publicKeyFile (PublicKeyFile), routeMetric (RouteMetric), routeTable (RouteTable) |
spec.wlan |
WLAN | physicalDevice (PhysicalDevice), type (Type), wds (WDS) |
spec.xfrm |
Xfrm | independent (Independent), interfaceId (InterfaceId) |
Network¶
A systemd-networkd .network file, which configures the network devices it matches: their addresses, routes, DHCP and the virtual devices on them.
apiVersion: networkd.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own.
Each field of spec is a section of the unit: an object, or a list of objects for a
section written more than once. Each key of a section is networkd's key in camelCase and takes
a value, or a list for a key written more than once. The table gives each section and key as
networkd spells it.
| Field | networkd section | Keys |
|---|---|---|
spec.address |
Address | addPrefixRoute (AddPrefixRoute), address (Address), autoJoin (AutoJoin), broadcast (Broadcast), duplicateAddressDetection (DuplicateAddressDetection), homeAddress (HomeAddress), label (Label), manageTemporaryAddress (ManageTemporaryAddress), netLabel (NetLabel), nftSet (NFTSet), peer (Peer), preferredLifetime (PreferredLifetime), prefixRoute (PrefixRoute), routeMetric (RouteMetric), scope (Scope) |
spec.bandMultiQueueing |
BandMultiQueueing | handle (Handle), parent (Parent) |
spec.bfifo |
BFIFO | handle (Handle), limitBytes (LimitBytes), parent (Parent) |
spec.bridge |
Bridge | allowPortToBeRoot (AllowPortToBeRoot), cost (Cost), fastLeave (FastLeave), hairPin (HairPin), isolated (Isolated), learning (Learning), locked (Locked), macAuthenticationBypass (MACAuthenticationBypass), multicastFlood (MulticastFlood), multicastRouter (MulticastRouter), multicastToUnicast (MulticastToUnicast), neighborSuppression (NeighborSuppression), priority (Priority), proxyARP (ProxyARP), proxyARPWiFi (ProxyARPWiFi), unicastFlood (UnicastFlood), useBPDU (UseBPDU), vlanTunnel (VLANTunnel) |
spec.bridgeFDB |
BridgeFDB | associatedWith (AssociatedWith), destination (Destination), macAddress (MACAddress), outgoingInterface (OutgoingInterface), vlanId (VLANId), vni (VNI) |
spec.bridgeMDB |
BridgeMDB | multicastGroupAddress (MulticastGroupAddress), vlanId (VLANId) |
spec.bridgeVLAN |
BridgeVLAN | egressUntagged (EgressUntagged), pvid (PVID), vlan (VLAN) |
spec.cake |
CAKE | ackFilter (AckFilter), autoRateIngress (AutoRateIngress), bandwidth (Bandwidth), compensationMode (CompensationMode), firewallMark (FirewallMark), flowIsolationMode (FlowIsolationMode), handle (Handle), mpuBytes (MPUBytes), nat (NAT), overheadBytes (OverheadBytes), parent (Parent), priorityQueueingPreset (PriorityQueueingPreset), rttSec (RTTSec), splitGSO (SplitGSO), useRawPacketSize (UseRawPacketSize), wash (Wash) |
spec.can |
CAN | bitRate (BitRate), busErrorReporting (BusErrorReporting), classicDataLengthCode (ClassicDataLengthCode), dataBitRate (DataBitRate), dataPhaseBufferSegment1 (DataPhaseBufferSegment1), dataPhaseBufferSegment2 (DataPhaseBufferSegment2), dataPropagationSegment (DataPropagationSegment), dataSamplePoint (DataSamplePoint), dataSyncJumpWidth (DataSyncJumpWidth), dataTimeQuantaNSec (DataTimeQuantaNSec), fdMode (FDMode), fdNonISO (FDNonISO), listenOnly (ListenOnly), loopback (Loopback), oneShot (OneShot), phaseBufferSegment1 (PhaseBufferSegment1), phaseBufferSegment2 (PhaseBufferSegment2), presumeACK (PresumeACK), propagationSegment (PropagationSegment), restartSec (RestartSec), samplePoint (SamplePoint), syncJumpWidth (SyncJumpWidth), termination (Termination), timeQuantaNSec (TimeQuantaNSec), tripleSampling (TripleSampling) |
spec.classfulMultiQueueing |
ClassfulMultiQueueing | handle (Handle), parent (Parent) |
spec.controlledDelay |
ControlledDelay | ceThresholdSec (CEThresholdSec), ecn (ECN), handle (Handle), intervalSec (IntervalSec), packetLimit (PacketLimit), parent (Parent), targetSec (TargetSec) |
spec.deficitRoundRobinScheduler |
DeficitRoundRobinScheduler | handle (Handle), parent (Parent) |
spec.deficitRoundRobinSchedulerClass |
DeficitRoundRobinSchedulerClass | classId (ClassId), parent (Parent), quantumBytes (QuantumBytes) |
spec.dhcp |
DHCP | anonymize (Anonymize), clientIdentifier (ClientIdentifier), criticalConnection (CriticalConnection), duidRawData (DUIDRawData), duidType (DUIDType), forceDHCPv6PDOtherInformation (ForceDHCPv6PDOtherInformation), hostname (Hostname), iaid (IAID), listenPort (ListenPort), rapidCommit (RapidCommit), requestBroadcast (RequestBroadcast), routeMetric (RouteMetric), routeTable (RouteTable), sendHostname (SendHostname), useDNS (UseDNS), useDomainName (UseDomainName), useDomains (UseDomains), useHostname (UseHostname), useMTU (UseMTU), useNTP (UseNTP), useRoutes (UseRoutes), useTimezone (UseTimezone), userClass (UserClass), vendorClassIdentifier (VendorClassIdentifier) |
spec.dhcpPrefixDelegation |
DHCPPrefixDelegation | announce (Announce), assign (Assign), manageTemporaryAddress (ManageTemporaryAddress), netLabel (NetLabel), nftSet (NFTSet), routeMetric (RouteMetric), subnetId (SubnetId), token (Token), uplinkInterface (UplinkInterface) |
spec.dhcpRelay |
DHCPRelay | agentAddress (AgentAddress), circuitId (CircuitId), extraOption (ExtraOption), gatewayAddress (GatewayAddress), interfacePriority (InterfacePriority), virtualSubnetSelection (VirtualSubnetSelection) |
spec.dhcpServer |
DHCPServer | bindToInterface (BindToInterface), bootFilename (BootFilename), bootServerAddress (BootServerAddress), bootServerName (BootServerName), defaultLeaseTimeSec (DefaultLeaseTimeSec), dns (DNS), domain (Domain), emitDNS (EmitDNS), emitDomain (EmitDomain), emitLPR (EmitLPR), emitNTP (EmitNTP), emitPOP3 (EmitPOP3), emitRouter (EmitRouter), emitSIP (EmitSIP), emitSMTP (EmitSMTP), emitTimezone (EmitTimezone), ipv6OnlyPreferredSec (IPv6OnlyPreferredSec), localLeaseDomain (LocalLeaseDomain), lpr (LPR), maxLeaseTimeSec (MaxLeaseTimeSec), ntp (NTP), persistLeases (PersistLeases), poolOffset (PoolOffset), poolSize (PoolSize), pop3 (POP3), rapidCommit (RapidCommit), relayAgentCircuitId (RelayAgentCircuitId), relayAgentRemoteId (RelayAgentRemoteId), relayTarget (RelayTarget), router (Router), sendOption (SendOption), sendVendorOption (SendVendorOption), serverAddress (ServerAddress), sip (SIP), smtp (SMTP), timezone (Timezone), uplinkInterface (UplinkInterface) |
spec.dhcpServerStaticLease |
DHCPServerStaticLease | address (Address), hostname (Hostname), macAddress (MACAddress) |
spec.dhcpv4 |
DHCPv4 | allowList (AllowList), anonymize (Anonymize), blackList (BlackList), bootp (BOOTP), clientIdentifier (ClientIdentifier), criticalConnection (CriticalConnection), denyList (DenyList), duidRawData (DUIDRawData), duidType (DUIDType), fallbackLeaseLifetimeSec (FallbackLeaseLifetimeSec), hostname (Hostname), iaid (IAID), initialAdvertisedReceiveWindow (InitialAdvertisedReceiveWindow), initialCongestionWindow (InitialCongestionWindow), ipServiceType (IPServiceType), ipv6OnlyMode (IPv6OnlyMode), label (Label), listenPort (ListenPort), maxAttempts (MaxAttempts), mudurl (MUDURL), netLabel (NetLabel), nftSet (NFTSet), quickAck (QuickAck), rapidCommit (RapidCommit), requestAddress (RequestAddress), requestBroadcast (RequestBroadcast), requestOptions (RequestOptions), routeMTUBytes (RouteMTUBytes), routeMetric (RouteMetric), routeTable (RouteTable), routesToDNS (RoutesToDNS), routesToNTP (RoutesToNTP), sendDecline (SendDecline), sendHostname (SendHostname), sendOption (SendOption), sendRelease (SendRelease), sendVendorOption (SendVendorOption), serverPort (ServerPort), socketPriority (SocketPriority), unassignedSubnetPolicy (UnassignedSubnetPolicy), use6RD (Use6RD), useCaptivePortal (UseCaptivePortal), useDNR (UseDNR), useDNS (UseDNS), useDomainName (UseDomainName), useDomains (UseDomains), useGateway (UseGateway), useHostname (UseHostname), useMTU (UseMTU), useNTP (UseNTP), useRoutes (UseRoutes), useSIP (UseSIP), useTimezone (UseTimezone), userClass (UserClass), vendorClassIdentifier (VendorClassIdentifier) |
spec.dhcpv6 |
DHCPv6 | duidRawData (DUIDRawData), duidType (DUIDType), forceDHCPv6PDOtherInformation (ForceDHCPv6PDOtherInformation), hostname (Hostname), iaid (IAID), mudurl (MUDURL), netLabel (NetLabel), nftSet (NFTSet), prefixDelegationHint (PrefixDelegationHint), rapidCommit (RapidCommit), requestOptions (RequestOptions), routeMetric (RouteMetric), routeTable (RouteTable), sendHostname (SendHostname), sendOption (SendOption), sendRelease (SendRelease), sendVendorOption (SendVendorOption), unassignedSubnetPolicy (UnassignedSubnetPolicy), useAddress (UseAddress), useCaptivePortal (UseCaptivePortal), useDNR (UseDNR), useDNS (UseDNS), useDelegatedPrefix (UseDelegatedPrefix), useDomains (UseDomains), useHostname (UseHostname), useNTP (UseNTP), useSIP (UseSIP), userClass (UserClass), vendorClass (VendorClass), withoutRA (WithoutRA) |
spec.dhcpv6PrefixDelegation |
DHCPv6PrefixDelegation | announce (Announce), assign (Assign), manageTemporaryAddress (ManageTemporaryAddress), routeMetric (RouteMetric), subnetId (SubnetId), token (Token) |
spec.enhancedTransmissionSelection |
EnhancedTransmissionSelection | bands (Bands), handle (Handle), parent (Parent), priorityMap (PriorityMap), quantumBytes (QuantumBytes), strictBands (StrictBands) |
spec.fairQueueing |
FairQueueing | buckets (Buckets), ceThresholdSec (CEThresholdSec), flowLimit (FlowLimit), handle (Handle), initialQuantum (InitialQuantum), initialQuantumBytes (InitialQuantumBytes), maximumRate (MaximumRate), orphanMask (OrphanMask), pacing (Pacing), packetLimit (PacketLimit), parent (Parent), quantum (Quantum), quantumBytes (QuantumBytes) |
spec.fairQueueingControlledDelay |
FairQueueingControlledDelay | ceThresholdSec (CEThresholdSec), ecn (ECN), flows (Flows), handle (Handle), intervalSec (IntervalSec), memoryLimit (MemoryLimit), memoryLimitBytes (MemoryLimitBytes), packetLimit (PacketLimit), parent (Parent), quantum (Quantum), quantumBytes (QuantumBytes), targetSec (TargetSec) |
spec.flowQueuePIE |
FlowQueuePIE | handle (Handle), packetLimit (PacketLimit), parent (Parent) |
spec.genericRandomEarlyDetection |
GenericRandomEarlyDetection | defaultVirtualQueue (DefaultVirtualQueue), genericRIO (GenericRIO), handle (Handle), parent (Parent), virtualQueues (VirtualQueues) |
spec.heavyHitterFilter |
HeavyHitterFilter | handle (Handle), packetLimit (PacketLimit), parent (Parent) |
spec.hierarchyTokenBucket |
HierarchyTokenBucket | defaultClass (DefaultClass), handle (Handle), parent (Parent), rateToQuantum (RateToQuantum) |
spec.hierarchyTokenBucketClass |
HierarchyTokenBucketClass | bufferBytes (BufferBytes), ceilBufferBytes (CeilBufferBytes), ceilRate (CeilRate), classId (ClassId), mtuBytes (MTUBytes), overheadBytes (OverheadBytes), parent (Parent), priority (Priority), quantumBytes (QuantumBytes), rate (Rate) |
spec.ipoib |
IPoIB | ignoreUserspaceMulticastGroups (IgnoreUserspaceMulticastGroups), mode (Mode) |
spec.ipv6AcceptRA |
IPv6AcceptRA | blackList (BlackList), denyList (DenyList), dhcpv6Client (DHCPv6Client), netLabel (NetLabel), nftSet (NFTSet), prefixAllowList (PrefixAllowList), prefixDenyList (PrefixDenyList), quickAck (QuickAck), routeAllowList (RouteAllowList), routeDenyList (RouteDenyList), routeMetric (RouteMetric), routeTable (RouteTable), routerAllowList (RouterAllowList), routerDenyList (RouterDenyList), token (Token), useAutonomousPrefix (UseAutonomousPrefix), useCaptivePortal (UseCaptivePortal), useDNR (UseDNR), useDNS (UseDNS), useDomains (UseDomains), useGateway (UseGateway), useHopLimit (UseHopLimit), useICMP6RateLimit (UseICMP6RateLimit), useMTU (UseMTU), useOnLinkPrefix (UseOnLinkPrefix), usePREF64 (UsePREF64), useReachableTime (UseReachableTime), useRedirect (UseRedirect), useRetransmissionTime (UseRetransmissionTime), useRoutePrefix (UseRoutePrefix) |
spec.ipv6AddressLabel |
IPv6AddressLabel | label (Label), prefix (Prefix) |
spec.ipv6PREF64Prefix |
IPv6PREF64Prefix | lifetimeSec (LifetimeSec), prefix (Prefix) |
spec.ipv6Prefix |
IPv6Prefix | addressAutoconfiguration (AddressAutoconfiguration), assign (Assign), onLink (OnLink), preferredLifetimeSec (PreferredLifetimeSec), prefix (Prefix), routeMetric (RouteMetric), token (Token), validLifetimeSec (ValidLifetimeSec) |
spec.ipv6PrefixDelegation |
IPv6PrefixDelegation | dns (DNS), dnsLifetimeSec (DNSLifetimeSec), domains (Domains), emitDNS (EmitDNS), emitDomains (EmitDomains), managed (Managed), otherInformation (OtherInformation), routerLifetimeSec (RouterLifetimeSec), routerPreference (RouterPreference) |
spec.ipv6RoutePrefix |
IPv6RoutePrefix | lifetimeSec (LifetimeSec), preference (Preference), route (Route) |
spec.ipv6SendRA |
IPv6SendRA | dns (DNS), dnsLifetimeSec (DNSLifetimeSec), domains (Domains), emitDNS (EmitDNS), emitDomains (EmitDomains), homeAgent (HomeAgent), homeAgentLifetimeSec (HomeAgentLifetimeSec), homeAgentPreference (HomeAgentPreference), hopLimit (HopLimit), managed (Managed), otherInformation (OtherInformation), reachableTimeSec (ReachableTimeSec), retransmitSec (RetransmitSec), routerLifetimeSec (RouterLifetimeSec), routerPreference (RouterPreference), uplinkInterface (UplinkInterface) |
spec.link |
Link | activationPolicy (ActivationPolicy), allMulticast (AllMulticast), arp (ARP), group (Group), macAddress (MACAddress), mtuBytes (MTUBytes), multicast (Multicast), promiscuous (Promiscuous), requiredFamilyForOnline (RequiredFamilyForOnline), requiredForOnline (RequiredForOnline), unmanaged (Unmanaged) |
spec.lldp |
LLDP | mudurl (MUDURL) |
spec.match |
Match | architecture (Architecture), bssid (BSSID), credential (Credential), driver (Driver), firmware (Firmware), host (Host), kernelCommandLine (KernelCommandLine), kernelVersion (KernelVersion), kind (Kind), macAddress (MACAddress), machineTag (MachineTag), name (Name), path (Path), permanentMACAddress (PermanentMACAddress), property (Property), ssid (SSID), type (Type), version (Version), virtualization (Virtualization), wlanInterfaceType (WLANInterfaceType) |
spec.mobileNetwork |
MobileNetwork | allowRoaming (AllowRoaming), allowedAuthenticationMechanisms (AllowedAuthenticationMechanisms), apn (APN), ipFamily (IPFamily), operatorId (OperatorId), password (Password), pin (PIN), routeMetric (RouteMetric), useGateway (UseGateway), user (User) |
spec.neighbor |
Neighbor | address (Address), linkLayerAddress (LinkLayerAddress), macAddress (MACAddress) |
spec.network |
Network | activeSlave (ActiveSlave), address (Address), batmanAdvanced (BatmanAdvanced), bindCarrier (BindCarrier), bond (Bond), bridge (Bridge), configureWithoutCarrier (ConfigureWithoutCarrier), defaultRouteOnDevice (DefaultRouteOnDevice), description (Description), dhcp (DHCP), dhcpPrefixDelegation (DHCPPrefixDelegation), dhcpRelay (DHCPRelay), dhcpServer (DHCPServer), dhcpv6PrefixDelegation (DHCPv6PrefixDelegation), dns (DNS), dnsDefaultRoute (DNSDefaultRoute), dnsOverTLS (DNSOverTLS), dnssec (DNSSEC), dnssecNegativeTrustAnchors (DNSSECNegativeTrustAnchors), domains (Domains), emitLLDP (EmitLLDP), gateway (Gateway), ignoreCarrierLoss (IgnoreCarrierLoss), ipForward (IPForward), ipMasquerade (IPMasquerade), ipoib (IPoIB), ipv4AcceptLocal (IPv4AcceptLocal), ipv4DuplicateAddressDetectionTimeoutSec (IPv4DuplicateAddressDetectionTimeoutSec), ipv4Forwarding (IPv4Forwarding), ipv4LL (IPv4LL), ipv4LLRoute (IPv4LLRoute), ipv4LLStartAddress (IPv4LLStartAddress), ipv4ProxyARP (IPv4ProxyARP), ipv4ProxyARPPrivateVLAN (IPv4ProxyARPPrivateVLAN), ipv4ReversePathFilter (IPv4ReversePathFilter), ipv4RouteLocalnet (IPv4RouteLocalnet), ipv4SrcValidMark (IPv4SrcValidMark), ipv6AcceptRA (IPv6AcceptRA), ipv6AcceptRouterAdvertisements (IPv6AcceptRouterAdvertisements), ipv6DuplicateAddressDetection (IPv6DuplicateAddressDetection), ipv6Forwarding (IPv6Forwarding), ipv6HopLimit (IPv6HopLimit), ipv6LinkLocalAddressGenerationMode (IPv6LinkLocalAddressGenerationMode), ipv6MTUBytes (IPv6MTUBytes), ipv6PrefixDelegation (IPv6PrefixDelegation), ipv6PrivacyExtensions (IPv6PrivacyExtensions), ipv6ProxyNDP (IPv6ProxyNDP), ipv6ProxyNDPAddress (IPv6ProxyNDPAddress), ipv6RetransmissionTimeSec (IPv6RetransmissionTimeSec), ipv6SendRA (IPv6SendRA), ipv6StableSecretAddress (IPv6StableSecretAddress), ipv6Token (IPv6Token), ipvlan (IPVLAN), ipvtap (IPVTAP), keepConfiguration (KeepConfiguration), keepMaster (KeepMaster), l2tp (L2TP), linkLocalAddressing (LinkLocalAddressing), lldp (LLDP), llmnr (LLMNR), macsec (MACsec), macvlan (MACVLAN), macvtap (MACVTAP), mplsRouting (MPLSRouting), multicastDNS (MulticastDNS), multicastIGMPVersion (MulticastIGMPVersion), ntp (NTP), primarySlave (PrimarySlave), proxyARP (ProxyARP), proxyNeighbor (ProxyNeighbor), tunnel (Tunnel), useDomains (UseDomains), vlan (VLAN), vrf (VRF), vxlan (VXLAN), xfrm (Xfrm) |
spec.networkEmulator |
NetworkEmulator | delayJitterSec (DelayJitterSec), delaySec (DelaySec), duplicateRate (DuplicateRate), handle (Handle), lossRate (LossRate), packetLimit (PacketLimit), parent (Parent) |
spec.nextHop |
NextHop | blackhole (Blackhole), family (Family), gateway (Gateway), group (Group), id (Id), onLink (OnLink) |
spec.pfifo |
PFIFO | handle (Handle), packetLimit (PacketLimit), parent (Parent) |
spec.pfifoFast |
PFIFOFast | handle (Handle), parent (Parent) |
spec.pfifoHeadDrop |
PFIFOHeadDrop | handle (Handle), packetLimit (PacketLimit), parent (Parent) |
spec.pie |
PIE | handle (Handle), packetLimit (PacketLimit), parent (Parent) |
spec.qDisc |
QDisc | handle (Handle), parent (Parent) |
spec.quickFairQueueing |
QuickFairQueueing | handle (Handle), parent (Parent) |
spec.quickFairQueueingClass |
QuickFairQueueingClass | classId (ClassId), maxPacketBytes (MaxPacketBytes), parent (Parent), weight (Weight) |
spec.route |
Route | destination (Destination), fastOpenNoCookie (FastOpenNoCookie), gateway (Gateway), gatewayOnLink (GatewayOnLink), gatewayOnlink (GatewayOnlink), hopLimit (HopLimit), initialAdvertisedReceiveWindow (InitialAdvertisedReceiveWindow), initialCongestionWindow (InitialCongestionWindow), ipv6Preference (IPv6Preference), metric (Metric), mtuBytes (MTUBytes), multiPathRoute (MultiPathRoute), nextHop (NextHop), preferredSource (PreferredSource), protocol (Protocol), quickAck (QuickAck), scope (Scope), source (Source), table (Table), tcpAdvertisedMaximumSegmentSize (TCPAdvertisedMaximumSegmentSize), tcpCongestionControlAlgorithm (TCPCongestionControlAlgorithm), tcpRetransmissionTimeoutSec (TCPRetransmissionTimeoutSec), ttlPropagate (TTLPropagate), type (Type) |
spec.routingPolicyRule |
RoutingPolicyRule | destinationPort (DestinationPort), family (Family), firewallMark (FirewallMark), from (From), goTo (GoTo), incomingInterface (IncomingInterface), invertRule (InvertRule), ipProtocol (IPProtocol), l3MasterDevice (L3MasterDevice), outgoingInterface (OutgoingInterface), priority (Priority), sourcePort (SourcePort), suppressInterfaceGroup (SuppressInterfaceGroup), suppressPrefixLength (SuppressPrefixLength), table (Table), to (To), type (Type), typeOfService (TypeOfService), user (User) |
spec.sriov |
SR-IOV | linkState (LinkState), macAddress (MACAddress), macSpoofCheck (MACSpoofCheck), qualityOfService (QualityOfService), queryReceiveSideScaling (QueryReceiveSideScaling), trust (Trust), virtualFunction (VirtualFunction), vlanId (VLANId), vlanProtocol (VLANProtocol) |
spec.stochasticFairBlue |
StochasticFairBlue | handle (Handle), packetLimit (PacketLimit), parent (Parent) |
spec.stochasticFairnessQueueing |
StochasticFairnessQueueing | handle (Handle), parent (Parent), perturbPeriodSec (PerturbPeriodSec) |
spec.tokenBucketFilter |
TokenBucketFilter | burst (Burst), burstBytes (BurstBytes), handle (Handle), latencySec (LatencySec), limitBytes (LimitBytes), limitSize (LimitSize), mpuBytes (MPUBytes), mtuBytes (MTUBytes), parent (Parent), peakRate (PeakRate), rate (Rate) |
spec.trafficControlQueueingDiscipline |
TrafficControlQueueingDiscipline | networkEmulatorDelayJitterSec (NetworkEmulatorDelayJitterSec), networkEmulatorDelaySec (NetworkEmulatorDelaySec), networkEmulatorDuplicateRate (NetworkEmulatorDuplicateRate), networkEmulatorLossRate (NetworkEmulatorLossRate), networkEmulatorPacketLimit (NetworkEmulatorPacketLimit), parent (Parent) |
spec.trivialLinkEqualizer |
TrivialLinkEqualizer | handle (Handle), id (Id), parent (Parent) |
oci.chalkos.dev¶
The kinds of oci.chalkos.dev set how the node reaches OCI registries: the credentials of each host and the mirrors of a registry.
Mirror¶
The mirror endpoints that chalkd and containerd try, in order, before a registry itself.
apiVersion: oci.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own.
| Field | Type | Default | Description |
|---|---|---|---|
spec.endpoints |
list of string | required | URLs of the mirror's endpoints, which chalkd and containerd try in order before the registry itself. A path is where the endpoint serves the registry API, below <path>/v2 as containerd takes it. chalkd authenticates to an endpoint with the Registry of the endpoint's host, and an http:// endpoint needs that Registry to set insecure. |
spec.registry |
string | required | Host of the registry as image references name it, with its port unless it is 443; an IPv6 address in brackets. Unique among the Mirror documents, compared as registry hosts. |
Registry¶
The credentials and transport of an OCI registry host, with which chalkd pulls OS images and, on images that run Kubernetes, containerd pulls container images.
apiVersion: oci.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has a change rule.
| Field | Type | Default | Description |
|---|---|---|---|
spec.host |
string | required | Host of a registry or of a mirror's endpoint, as image references and endpoints name it, with its port unless it is 443; an IPv6 address in brackets. chalkd pulls OS images from this host with the Registry's credentials, over plain HTTP when insecure is set. On images that run Kubernetes, the kubelet hands these credentials to containerd for the container images of this host, and containerd sends them to every endpoint of the host's Mirror too, over plain HTTP to an endpoint whose host is insecure. The kubelet compares the host, in lower case and with its port, case-sensitively with the image's host as the pod spec writes it, so pods name the host in lower case. An IPv6 host with credentials needs its port, 443 included, for the kubelet to match it. Unique among the Registry documents, compared as registry hosts. |
spec.insecure |
boolean | false |
Whether chalkd and containerd reach this host over plain HTTP, with credentials and images unencrypted, and a Mirror may name an http:// endpoint on it. Without it, chalkd pulls over HTTPS alone, also from private and loopback addresses. |
spec.password |
secret reference or null | null |
Password or token of the user, from a Secret; null pulls anonymously. |
spec.username |
string or null | null |
User chalkd authenticates to the host as, with the password, and containerd too on images that run Kubernetes; null pulls anonymously. |
router.chalkos.dev¶
The kinds of router.chalkos.dev set how a router forwards and filters: its forwarding and reverse-path filter, its firewall's zones, policies and address sets, and its NAT rules. Only router images accept them.
AddressSet¶
Address ranges of one family, which the rules of FirewallPolicy and PolicyRoute documents name in a source or destination as {set: <name>}.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has a change rule.
| Field | Type | Default | Description |
|---|---|---|---|
spec.family |
one of ipv4, ipv6 |
required | Address family of the set. |
spec.prefixes |
list of address range | required | Address ranges of the set. |
BGP¶
A BGP instance of the router in one VRF: its AS number and router ID, how many equal paths it installs, its BFD timers, the networks it announces and the routes it imports from other VRFs.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 8 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.asn |
integer from 1 to 4294967295 | required | AS number of the instance. It stays while the BGP document keeps its name; a BGP document of another name replaces the old one, AS number included. |
spec.bfd.multiplier |
integer from 2 to 255 | 3 |
BFD packets in a row a peer may miss before the router takes it for down and ends the session. |
spec.bfd.receiveMs |
integer from 10 to 60000 | 300 |
Shortest interval in milliseconds at which the router accepts BFD packets of the peers with bfd. |
spec.bfd.transmitMs |
integer from 10 to 60000 | 300 |
Shortest interval in milliseconds at which the router sends BFD packets. |
spec.gracefulRestart |
boolean | false |
Whether the router keeps a peer's routes while the peer restarts and asks its peers to keep its own. |
spec.import |
object | {} |
Routes the instance takes from the BGP instances of other VRFs, which the kernel installs in this VRF's table with their next hops in the other VRF. Static routes of a VRF's links are not leaked. |
spec.import.ipv4 |
object or null | null |
IPv4 routes the instance takes from other VRFs' instances; null takes none. |
spec.import.ipv4.policy |
name of a RoutingPolicy or null | null |
RoutingPolicy that decides the routes the instance takes from all of vrfs; null takes every route. |
spec.import.ipv4.vrfs |
list of name of a VRF, or default |
required | VRFs whose BGP instances' routes of the family the instance takes, each once, by the names of their VRF documents or default. Each item is unique within the list. |
spec.import.ipv6 |
object or null | null |
IPv6 routes the instance takes from other VRFs' instances; null takes none. |
spec.import.ipv6.policy |
name of a RoutingPolicy or null | null |
RoutingPolicy that decides the routes the instance takes from all of vrfs; null takes every route. |
spec.import.ipv6.vrfs |
list of name of a VRF, or default |
required | VRFs whose BGP instances' routes of the family the instance takes, each once, by the names of their VRF documents or default. Each item is unique within the list. |
spec.multipath.asPathRelax |
boolean | false |
Whether paths through different neighbouring ASes count as equal when their AS paths are equally long, as for two leaves of a fabric. |
spec.multipath.ebgp |
integer from 1 to 64 | 1 |
Equal paths from external peers the router installs for one prefix at most. |
spec.multipath.ibgp |
integer from 1 to 64 | 1 |
Equal paths from internal peers the router installs for one prefix at most. |
spec.networks |
list of object | [] |
Networks the router announces to its peers. Each item is unique within the list by prefix as masked ranges. |
spec.networks[].policy |
name of a RoutingPolicy or null | null |
RoutingPolicy whose terms set the announcement's attributes; null announces it as it is. |
spec.networks[].prefix |
address range | required | Address range the router announces while its table holds a route to it. |
spec.routerID |
string | required | Router ID, an IPv4 address other than 0.0.0.0, a multicast address and 255.255.255.255, which the router's peers know it by; give an IPv6-only router one too. |
spec.vrf |
name of a VRF, or default |
"default" |
VRF document whose instance this is; default for the default VRF, which holds every link no VRF holds. Unique among the BGP documents. |
BGPPeer¶
A BGP neighbour of the router, or the neighbours on a set of interfaces or of a prefix: where to reach them, their AS, and what the router accepts from them and sends them in each address family.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 14 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.address |
IP address or null | null |
Unicast address of the neighbour beyond the router, neither loopback, link-local nor IPv4-mapped; excludes interface, interfaces and listen. |
spec.bfd |
boolean | false |
Whether the router checks the session's link with BFD, at the timers of the BGP document, and ends the session when BFD finds it down. |
spec.description |
string or null | null |
What the neighbour is, in up to 80 printable ASCII characters other than @, with a single space between two words. |
spec.extendedNextHop |
boolean | false |
Whether the router sends and accepts IPv4 routes with IPv6 next hops (RFC 8950). A peer at an IPv6 address or with an IPv6 listen range that exchanges IPv4 routes needs it. FRR negotiates it on sessions of interface and interfaces whatever this says. |
spec.families |
object | {} |
The address families the session exchanges routes of, and how. |
spec.families.ipv4 |
object or null | null |
IPv4 routes of the session; null exchanges none. |
spec.families.ipv4.defaultOriginate |
boolean | false |
Whether the router sends the peer a default route of the family: whatever its own table holds, or while defaultOriginateWhen holds. |
spec.families.ipv4.defaultOriginateWhen |
name of a PrefixList or null | null |
PrefixList of the family that decides when the router sends the default route of defaultOriginate: while the peer's VRF holds a route the list matches, from BGP, from the kernel, such as a route from DHCP, from router advertisements or a Network's [Route], or a link's prefix. Blackhole, unreachable and prohibit routes do not count. The router does not announce the routes it tracks. null sends the default route whatever the table holds. |
spec.families.ipv4.export |
name of a RoutingPolicy or null | null |
RoutingPolicy that decides the routes the router sends the peer; null sends every route the router has. |
spec.families.ipv4.import |
name of a RoutingPolicy or null | null |
RoutingPolicy that decides the routes the router accepts from the peer; null accepts every route. |
spec.families.ipv4.maxPrefix |
integer from 1 to 4294967295 or null | null |
Routes the router accepts from the peer at most; past them it ends the session. null sets no limit. |
spec.families.ipv6 |
object or null | null |
IPv6 routes of the session; null exchanges none. |
spec.families.ipv6.defaultOriginate |
boolean | false |
Whether the router sends the peer a default route of the family: whatever its own table holds, or while defaultOriginateWhen holds. |
spec.families.ipv6.defaultOriginateWhen |
name of a PrefixList or null | null |
PrefixList of the family that decides when the router sends the default route of defaultOriginate: while the peer's VRF holds a route the list matches, from BGP, from the kernel, such as a route from DHCP, from router advertisements or a Network's [Route], or a link's prefix. Blackhole, unreachable and prohibit routes do not count. The router does not announce the routes it tracks. null sends the default route whatever the table holds. |
spec.families.ipv6.export |
name of a RoutingPolicy or null | null |
RoutingPolicy that decides the routes the router sends the peer; null sends every route the router has. |
spec.families.ipv6.import |
name of a RoutingPolicy or null | null |
RoutingPolicy that decides the routes the router accepts from the peer; null accepts every route. |
spec.families.ipv6.maxPrefix |
integer from 1 to 4294967295 or null | null |
Routes the router accepts from the peer at most; past them it ends the session. null sets no limit. |
spec.interface |
string or null | null |
Interface on whose link the router finds the neighbour by its IPv6 link-local address, without an address of its own on the link; excludes address, interfaces and listen. A name that reads as an address is refused. |
spec.interfaces |
list of string or null | null |
Interfaces, by name or glob, a glob being a prefix followed by *, with a session each, as for interface; a glob stands for the interfaces of the peer's VRF that the node's Network documents name in a [Match] section's Name=. Excludes address, interface and listen. |
spec.listen |
object or null | null |
Accept a session from every neighbour whose address lies in range, which then shares the peer's settings; the router opens no session itself. Excludes address, interface and interfaces. |
spec.listen.range |
address range | required | Prefix whose addresses may open a session with the router; neither link-local, loopback, multicast nor IPv4-mapped. |
spec.password |
secret reference or null | null |
Key of a Secret that holds the session's TCP MD5 password, of 80 characters at most and no white space; null for none. The Secret's name and key hold letters, digits, ., _ and - alone. |
spec.remoteAS |
one of external, internal or integer from 1 to 4294967295 |
required | AS of the neighbour: a number, external for any AS but the router's, or internal for the router's own. |
spec.shutdown |
boolean | false |
Whether the router keeps the session down while the document stays. |
spec.vrf |
name of a VRF, or default |
"default" |
VRF document whose BGP instance runs the session; default for the default VRF. The peer's interfaces are links of that VRF. |
CommunityList¶
BGP communities that a RoutingPolicy term matches routes against: a route that carries one of them matches.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has a change rule.
| Field | Type | Default | Description |
|---|---|---|---|
spec.communities |
list of string | required | The communities: standard communities <AS>:<value> of 16-bit numbers, or large ones <AS>:<value>:<value> of 32-bit numbers, without leading zeros. Each item is unique within the list. |
DHCPRelay¶
Links whose clients' DHCP requests the router relays to DHCP servers elsewhere, DHCPv4 to the IPv4 servers and DHCPv6 to the IPv6 ones.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has a change rule.
| Field | Type | Default | Description |
|---|---|---|---|
spec.interfaces |
list of string | required | Links the clients ask on, each by its full name, without a glob: links of one VRF, each of which a Network document matching it by Name= alone gives a static address of each family the servers have, a global one for IPv6. A link takes one relay. Each item is unique among the DHCPRelay documents. |
spec.servers |
list of IP address | required | Unicast addresses of the DHCP servers, which the router reaches through the links' VRF: IPv4 servers get the links' DHCPv4 requests and IPv6 servers their DHCPv6 requests. A DHCPv6 server answers relayed requests on such an address, as Kea's does on an interface given as <name>/<address>. Each item is unique within the list, compared as addresses. |
DHCPSubnet¶
A subnet the router's DHCP server leases IPv4 or IPv6 addresses of on its interfaces: pools and reservations, the options its clients get, the files PXE clients boot and, for IPv6, the prefixes it delegates to other routers.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 23 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.boot |
object or null | null |
Files PXE clients of an IPv4 subnet boot, by firmware; boot files are served elsewhere. null serves none. |
spec.boot.bios |
string or null | null |
File of clients with BIOS firmware, of architecture 0 in option 93, loaded over TFTP from server. |
spec.boot.ipxe |
string or null | null |
Script or file of clients that run iPXE already, whose user class (option 77) is iPXE; they get it instead of bios and uefi, so that iPXE does not load itself again. |
spec.boot.server |
IP address or null | null |
IPv4 address of the TFTP server the files are on, the DHCP header's next server; needed with bios or uefi, whose firmware loads them over TFTP. null for none, as for an ipxe script of an HTTP URL alone. |
spec.boot.uefi |
string or null | null |
File of clients with x86-64 UEFI firmware, of architecture 7 or 9 in option 93, loaded over TFTP from server. |
spec.dns |
list of IP address | [] |
DNS servers the clients ask, addresses of the subnet's family. Holds 16 items at most. |
spec.domain |
string or null | null |
Domain of the clients' names, which they also search; null gives none. |
spec.gateway |
IP address or null | null |
Router the clients route through, inside an IPv4 subnet and neither its network nor its broadcast address; null gives them none. IPv6 clients learn their routers from router advertisements. |
spec.interfaces |
list of string | required | Links the server answers on, each by its full name, without a glob, and once: links of one VRF, each of which a Network document matching it by Name= alone gives a static address in the subnet; one link for an IPv6 subnet. A link takes one subnet of each family. Each item is unique within the list. |
spec.leaseTime |
string | "12h" |
How long a lease lasts, and a delegated prefix: a number and s, m, h or d, 136 years at most. IPv6 clients prefer their addresses for as long. |
spec.pools |
list of object | [] |
Ranges the server leases addresses from to any client: inside the subnet, apart from each other and from the reservations, and holding none of the subnet's network and broadcast addresses, an IPv6 subnet's first address and the router's, the gateway's and the DNS and boot servers' addresses; empty leases the reservations alone. Holds 32 items at most. |
spec.pools[].first |
IP address | required | First address of the pool. |
spec.pools[].last |
IP address | required | Last address of the pool, no lower than the first. |
spec.prefixDelegation |
object or null | null |
Prefixes the IPv6 server delegates to routers on the link that ask for one, such as a home router's LAN; the router routes each to the link-local address that asked for it, for as long as the lease lasts. null delegates none. |
spec.prefixDelegation.length |
integer from 1 to 128 | required | Length of each delegated prefix, longer than the range's. |
spec.prefixDelegation.prefix |
address range | required | IPv6 range the delegated prefixes are taken from, apart from ::/8, fe80::/10, ff00::/8 and the subnets of the VRF. |
spec.reservations |
list of object | [] |
Clients that always get the same address, by their MAC address. Holds 512 items at most. Each item is unique within the list by mac in lower case. Each item is unique within the list by address as addresses. |
spec.reservations[].address |
IP address | required | Address the client always gets, inside the subnet and outside its pools, and none of the subnet's network and broadcast addresses, an IPv6 subnet's first address and the router's, the gateway's and the DNS and boot servers' addresses. |
spec.reservations[].hostname |
string or null | null |
Name the client gets; null gives none. |
spec.reservations[].mac |
string | required | MAC address of the client, in lower case. A DHCPv6 server learns it from the client's DUID or link-local address, which not every client derives from it. |
spec.subnet |
address range | required | Range the subnet's addresses are in, whose family the server's is: an IPv4 range of 30 bits at most or an IPv6 range of 120 bits at most. |
FirewallPolicy¶
What the router's firewall does with new connections from one zone to another, or to the router itself: rules in order, then a default.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 5 change rules. No two documents share from and to.
| Field | Type | Default | Description |
|---|---|---|---|
spec.default |
one of accept, drop, reject |
"drop" |
What happens to a connection no rule matches; reject answers with an administratively prohibited error. |
spec.from |
name of a FirewallZone, or local |
required | FirewallZone the connections come from. |
spec.rules |
list of object | [] |
Rules in order: the first that matches a connection decides. |
spec.rules[].action |
one of accept, drop, reject |
required | What happens to a connection the rule matches; reject answers with an administratively prohibited error. |
spec.rules[].destination |
object or null | null |
Destination addresses: the ranges of an AddressSet in set, or address ranges in cidrs; null matches every destination. |
spec.rules[].destination.cidrs |
list of address range or null | null |
Address ranges that match; excludes set. In each family the rule matches the ranges of that family. |
spec.rules[].destination.set |
name of an AddressSet or null | null |
AddressSet whose ranges match; excludes cidrs. |
spec.rules[].destinationPorts |
list of integer from 1 to 65535 or range of ports | [] |
Destination ports, each a port or a range <first>-<last>, with the protocol tcp, udp or sctp; empty matches every port. |
spec.rules[].family |
one of ipv4, ipv6 or null |
null |
Address family the rule matches; null matches each family its protocol and addresses leave. |
spec.rules[].icmpTypes |
list of one of echo-request, echo-reply, destination-unreachable, time-exceeded, parameter-problem, packet-too-big |
[] |
ICMP or ICMPv6 types, with the protocol icmp or icmpv6; empty matches every type. packet-too-big is ICMPv6's. |
spec.rules[].log |
boolean | false |
Whether the kernel logs each packet the rule matches, prefixed with the policy's name and the rule's number. |
spec.rules[].protocol |
one of tcp, udp, sctp, icmp, icmpv6, gre, esp, ah or null |
null |
Protocol the rule matches; null matches every protocol. icmp is IPv4's and icmpv6 IPv6's. |
spec.rules[].source |
object or null | null |
Source addresses: the ranges of an AddressSet in set, or address ranges in cidrs; null matches every source. |
spec.rules[].source.cidrs |
list of address range or null | null |
Address ranges that match; excludes set. In each family the rule matches the ranges of that family. |
spec.rules[].source.set |
name of an AddressSet or null | null |
AddressSet whose ranges match; excludes cidrs. |
spec.rules[].sourcePorts |
list of integer from 1 to 65535 or range of ports | [] |
Source ports, each a port or a range <first>-<last>, with the protocol tcp, udp or sctp; empty matches every port. |
spec.to |
name of a FirewallZone, or local |
required | FirewallZone the connections go to, or local for connections to the router itself. |
FirewallZone¶
A zone of the router's firewall: interfaces and VRFs whose connections the FirewallPolicy documents treat alike. The zone local is the router itself and has no document.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 2 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.interfaces |
list of string | [] |
Interfaces of the zone, by name or glob, a glob being a prefix followed by *. A link a VRF holds may be named here without its VRF, so that one VRF's links fall into several zones; the VRF itself is then in no other zone. Each item is unique among the FirewallZone documents. |
spec.vrfs |
list of name of a VRF | [] |
VRF documents whose links are all in the zone, those added later included; a VRF is in one zone at most. Each item is unique among the FirewallZone documents. |
NAT64¶
A stateful NAT64 of the router, an instance of Jool in a network namespace of its own that a link joins to its VRF: it translates IPv6 connections to addresses of its prefix into IPv4 connections to the address each embeds, from the addresses of its pool.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 9 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.pool4 |
list of object | [] |
IPv4 addresses, with their ports, that the translated connections leave from: addresses routed to the router, not addresses of its links, which the router answers itself. The rules refuse an address that a Network document gives a link. An address a link takes from DHCP passes them, and chalkos-nat64.service then fails without changing an instance; leave pool4 empty instead. Empty takes the address of the link a connection leaves through, with the ports 61001 to 65535, which the router masquerades. The pools of two NAT64s share no address, which the validator router checks. The firewall's NAT rules leave the translated connections alone. |
spec.pool4[].ports |
integer from 1 to 65535 or range of ports | "61001-65535" |
Ports, or ICMP identifiers, of the addresses the translated connections take: a port or a range <first>-<last> that leaves out the kernel's ephemeral ports, 32768 to 60999, which the router's own connections take. |
spec.pool4[].prefix |
address range | required | IPv4 addresses the translated connections leave from, a range of 65536 addresses at most. |
spec.pool4[].protocols |
list of one of tcp, udp, icmp |
["tcp","udp","icmp"] |
Protocols whose connections take the addresses and ports. Each item is unique within the list. |
spec.prefix |
address range | "64:ff9b::/96" |
IPv6 range whose addresses the NAT64 translates, each embedding an IPv4 address as RFC 6052 says: 32, 40, 48, 56, 64 or 96 bits, by default the well-known prefix. The router routes it to the NAT64's link in the NAT64's VRF, a route that BGP announces when BGP.spec.networks of that VRF names the prefix. The prefixes of the NAT64s of one VRF do not overlap, which the validator router checks. |
spec.vrf |
name of a VRF, or default |
"default" |
VRF document whose links route the prefix to the NAT64 and carry its translated connections; default for the default VRF. The NAT64 runs in the network namespace nat64-<name>, which the link n64-<name> joins to the VRF. |
NATRule¶
An address translation of the router, which applies whether or not any FirewallPolicy exists: masquerade or source NAT of connections that leave, destination NAT of connections that arrive.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 5 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.family |
one of ipv4, ipv6 |
"ipv4" |
Address family the rule translates. |
spec.in |
object or null | null |
Where the connections arrive, for dnat. |
spec.in.interface |
string or null | null |
Interface the connections use, by name or glob, a glob being a prefix followed by *; excludes zone. |
spec.in.zone |
name of a FirewallZone or null | null |
FirewallZone whose interfaces the connections use; excludes interface. |
spec.match.destination |
list of address range | [] |
Destination address ranges of the connections; empty matches every destination. |
spec.match.destinationPorts |
list of integer from 1 to 65535 or range of ports | [] |
Destination ports, each a port or a range <first>-<last>, with protocol; empty matches every port. |
spec.match.protocol |
one of tcp, udp, sctp or null |
null |
Protocol of the connections; null matches every protocol. |
spec.match.source |
list of address range | [] |
Source address ranges of the connections; empty matches every source. |
spec.out |
object or null | null |
Where the connections leave, for masquerade and snat. |
spec.out.interface |
string or null | null |
Interface the connections use, by name or glob, a glob being a prefix followed by *; excludes zone. |
spec.out.zone |
name of a FirewallZone or null | null |
FirewallZone whose interfaces the connections use; excludes interface. |
spec.to |
object or null | null |
What snat and dnat translate to. |
spec.to.address |
IP address | required | Address the rule translates to. |
spec.to.port |
integer from 1 to 65535 or null | null |
Port the rule translates to, with match.protocol; null keeps the port. |
spec.type |
one of masquerade, snat, dnat |
required | masquerade translates the source of a leaving connection to the address of the interface it leaves through, snat to to.address, and dnat the destination of an arriving connection to to.address. |
NextHop¶
A next hop of policy routing: the router at an address on one of the node's links, and a routing table of its own that holds a default route through it and an unreachable default route after it, so that the traffic is dropped while the link is down. PolicyRoute rules name it in to.nextHop; the rules that name one NextHop share its table, its route and its mark.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 4 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.address |
IP address | required | Address of the router the traffic leaves through: a unicast address, link-local ones included, and no IPv4-mapped IPv6 address. The rules that name the NextHop match packets of its family. |
spec.interface |
string | required | Link the next hop is on, which a Network document names alone in its [Match] section; the route through the next hop goes into that Network. |
spec.table |
integer from 1 to 4294967295 | required | Routing table of the next hop, which no other NextHop uses: none of 253, 254 and 255, the kernel's own, no VRF's table and no PolicyRoute rule's table. Unique among the NextHop documents. |
PolicyRoute¶
Policy routing of the router: rules that send the forwarded traffic they match, coming in on a zone's links, on interfaces or on any link, to a VRF's routing table, another table or a next hop, whatever its destination's route. The first rule that matches decides; documents apply in the order of their names.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 10 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.in |
object or null | null |
Where the traffic comes in: a zone or interfaces; null for every link. |
spec.in.interfaces |
list of string | [] |
Interfaces the traffic comes in on, by name or glob, a glob being a prefix followed by *; excludes zone. |
spec.in.zone |
name of a FirewallZone or null | null |
FirewallZone whose links the traffic comes in on; excludes interfaces. |
spec.rules |
list of object | required | Rules in order: the first that matches a packet decides where it goes. |
spec.rules[].match |
object | required | What the rule matches, at least one term: a rule for every packet says so, such as with source: {cidrs: [0.0.0.0/0]}. |
spec.rules[].match.destination |
object or null | null |
Destination addresses: the ranges of an AddressSet in set, or address ranges in cidrs; null matches every destination. |
spec.rules[].match.destination.cidrs |
list of address range or null | null |
Address ranges that match; excludes set. In each family the rule matches the ranges of that family. |
spec.rules[].match.destination.set |
name of an AddressSet or null | null |
AddressSet whose ranges match; excludes cidrs. |
spec.rules[].match.destinationPorts |
list of integer from 1 to 65535 or range of ports | [] |
Destination ports, each a port or a range <first>-<last>, with the protocol tcp, udp or sctp; empty matches every port. |
spec.rules[].match.dscp |
list of integer from 0 to 63 | [] |
DSCP values of the packets, each from 0 to 63; empty matches every value. |
spec.rules[].match.family |
one of ipv4, ipv6 or null |
null |
Address family the rule matches; null matches each family its protocol and addresses leave. |
spec.rules[].match.protocol |
one of tcp, udp, sctp, icmp, icmpv6, gre, esp, ah or null |
null |
Protocol the rule matches; null matches every protocol. icmp is IPv4's and icmpv6 IPv6's. |
spec.rules[].match.source |
object or null | null |
Source addresses: the ranges of an AddressSet in set, or address ranges in cidrs; null matches every source. |
spec.rules[].match.source.cidrs |
list of address range or null | null |
Address ranges that match; excludes set. In each family the rule matches the ranges of that family. |
spec.rules[].match.source.set |
name of an AddressSet or null | null |
AddressSet whose ranges match; excludes cidrs. |
spec.rules[].match.sourcePorts |
list of integer from 1 to 65535 or range of ports | [] |
Source ports, each a port or a range <first>-<last>, with the protocol tcp, udp or sctp; empty matches every port. |
spec.rules[].to |
object | required | Where the traffic the rule matches goes: vrf, table or nextHop. |
spec.rules[].to.nextHop |
name of a NextHop or null | null |
NextHop document whose router the traffic leaves through, by the default route of the NextHop's table; excludes vrf and table. Rules that name one NextHop share its table, its route and its mark. |
spec.rules[].to.table |
integer from 1 to 4294967295 or null | null |
Routing table that routes the traffic, by number: 254 is the main table. Not 255, the kernel's local table, no VRF's table, which vrf names, and no NextHop's table, which nextHop names. A destination the table has no route to takes the route it would take without the policy; excludes vrf and nextHop. |
spec.rules[].to.vrf |
name of a VRF or null | null |
VRF document whose routing table routes the traffic; excludes table and nextHop. |
PrefixList¶
Address ranges of one family that a RoutingPolicy term matches routes against: entries in order, the first that matches a route deciding.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has a change rule.
| Field | Type | Default | Description |
|---|---|---|---|
spec.entries |
list of object | required | Entries in order; a route no entry matches does not match the list. Each item is unique within the list by prefix as masked ranges, ge and le. |
spec.entries[].action |
one of permit, deny |
"permit" |
Whether a route the entry matches matches the list. |
spec.entries[].ge |
integer from 0 to 128 or null | null |
Shortest prefix length of a route within prefix that the entry matches, from the prefix's length; null matches prefix alone, unless le is given. |
spec.entries[].le |
integer from 0 to 128 or null | null |
Longest prefix length of a route within prefix that the entry matches; null matches prefix alone, unless ge is given. |
spec.entries[].prefix |
address range | required | Address range the entry matches. |
spec.family |
one of ipv4, ipv6 |
required | Address family of the list. |
Resolver¶
A DNS resolver of the router in one VRF, Unbound: the addresses it answers on, whom it answers, where it sends queries, and its DNS64 and local zones.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 9 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.allow |
list of address range | required | Address ranges of the clients the resolver answers; it refuses others, and the firewall accepts DNS from these alone. A family's whole range, 0.0.0.0/0 or ::/0, answers whoever reaches the addresses of listen: an open resolver, if one of them faces the internet. Each item is unique within the list, compared as masked ranges. |
spec.dns64 |
object or null | null |
DNS64: AAAA records the resolver synthesises for IPv4-only names, and its answer for ipv4only.arpa; null synthesises none. |
spec.dns64.prefix |
address range | "64:ff9b::/96" |
NAT64 prefix the resolver synthesises AAAA records in, from the A records of names that have no AAAA record. |
spec.dns64.synthesizeAll |
boolean | false |
Whether the resolver synthesises AAAA records from the A records of every name, and answers with them in place of the name's own AAAA records. A network that reaches the internet over NAT64 alone, such as one with only unique local addresses, has no route to the addresses of those records. |
spec.dnssec |
boolean | true |
Whether the resolver validates DNSSEC with the root's trust anchor of the image. The forwarders then pass DNSSEC records on. |
spec.forwarders |
list of IP address | [] |
Resolvers the router sends its queries to; empty resolves names itself, from the root servers. Each item is unique within the list, compared as addresses. |
spec.listen |
list of IP address | required | Addresses of the router in the resolver's VRF on which it answers on port 53, over UDP and TCP; the firewall accepts DNS on them from allow. Each item is unique within the list, compared as addresses. |
spec.localZones |
list of object | [] |
Zones the resolver answers from its own records. A record appears once, and a CNAME record's name holds no other record, which the output unbound checks. With dns64, no zone holds ipv4only.arpa, which DNS64 answers. Each item is unique within the list by name. |
spec.localZones[].name |
string | required | Name of the zone, in lower case and without the root's dot. |
spec.localZones[].records |
list of object | [] |
Records the router answers for names of the zone. |
spec.localZones[].records[].name |
string | required | Name of the record: the zone's name or a name below it. |
spec.localZones[].records[].ttl |
integer from 0 to 2147483647 | 3600 |
Seconds a resolver may keep the record. |
spec.localZones[].records[].type |
one of A, AAAA, CNAME, PTR, MX, SRV, TXT |
required | Type of the record. |
spec.localZones[].records[].value |
string | required | Data of the record, of up to 255 printable ASCII characters other than quotes and backslashes: an address for A and AAAA, a name for CNAME and PTR, <preference> <name> for MX, <priority> <weight> <port> <name> for SRV, and text for TXT. |
spec.localZones[].type |
one of static, transparent, typetransparent, redirect, refuse, deny, always_nxdomain |
"static" |
How Unbound answers names of the zone, as its local-zone types say: static answers from the records alone, transparent resolves the names the records lack, typetransparent also the types they lack, redirect answers every name below the zone with the zone's own records, refuse and deny refuse or drop the queries the records do not answer, and always_nxdomain answers that no name exists. |
spec.vrf |
name of a VRF, or default |
"default" |
VRF document on whose links the resolver answers and through whose links it sends its queries; default for the default VRF. Unique among the Resolver documents. |
Router¶
How the router forwards: the families it forwards, its reverse-path filter, how it spreads flows over equal-cost routes, its connection table and the interfaces that reach its node API.
apiVersion: router.chalkos.dev/v1alpha1
A node's config holds at most one. It has a change rule.
| Field | Type | Default | Description |
|---|---|---|---|
spec.conntrackMax |
integer of at least 1 or null | null |
Connections the router tracks at most, net.netfilter.nf_conntrack_max; null keeps the kernel's default, which follows the memory. |
spec.ecmpHash |
one of l3, l4 |
"l4" |
What the router hashes to pick one of several equal-cost routes for a flow, in both families: the addresses (l3), or the addresses, the protocol and the ports (l4). |
spec.forwarding.ipv4 |
boolean | true |
Whether the router forwards IPv4 packets between its interfaces. |
spec.forwarding.ipv6 |
boolean | true |
Whether the router forwards IPv6 packets between its interfaces. |
spec.management.interfaces |
list of string or null | null |
Interfaces, by name or glob, a glob being a prefix followed by *, on which the firewall accepts the node API, chalkd's TCP port 50000; null accepts it on every interface. |
spec.rpFilter |
one of off, loose, strict |
"loose" |
Reverse-path filter of the packets the router receives, in both families: strict drops a packet whose source the router would not route back out of the interface it came in on, loose one whose source it has no route to, and off drops none. DHCPv4 between ports 67 and 68 passes. |
RoutingPolicy¶
What the router does with the routes of a peer's family or of a network: terms in order, the first that matches a route deciding, then a default.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 4 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.default |
one of accept, reject |
"reject" |
What the router does with a route no term matches. |
spec.terms |
list of object | [] |
Terms in order: the first whose match holds for a route decides. |
spec.terms[].match.asPath |
string or null | null |
Regular expression the route's AS path matches, with _ for the start, the end or a space between two ASes; null matches every path. It holds up to 200 digits, single spaces and _^$.*+?()|{},-. The schema and rules check these characters alone; the output frr refuses an expression that bgpd cannot compile. |
spec.terms[].match.communityList |
name of a CommunityList or null | null |
CommunityList one of whose communities the route carries; null matches every route. |
spec.terms[].match.prefixList |
name of a PrefixList or null | null |
PrefixList the route's prefix matches; null matches every prefix. |
spec.terms[].then |
object | required | |
spec.terms[].then.action |
one of accept, reject |
required | Whether the router takes a route the term matches. |
spec.terms[].then.addCommunities |
list of string | [] |
Communities added to the route: standard communities <AS>:<value> of 16-bit numbers, or large ones <AS>:<value>:<value> of 32-bit numbers, without leading zeros. |
spec.terms[].then.localPref |
integer from 0 to 4294967295 or null | null |
Local preference the route gets; null keeps it. |
spec.terms[].then.med |
integer from 0 to 4294967295 or null | null |
Multi-exit discriminator the route gets; null keeps it. |
spec.terms[].then.prepend |
integer from 1 to 10 or null | null |
How often the router puts its own AS number in front of the route's AS path; null puts none. |
spec.terms[].then.removeCommunities |
list of string | [] |
Communities removed from the route. |
TimeServer¶
The router's NTP server, chrony: the addresses it answers on, whom it answers, and whether it serves its own clock when it follows no time server.
apiVersion: router.chalkos.dev/v1alpha1
A node's config holds at most one. It has 2 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.allow |
list of address range | required | Address ranges of the clients the time server answers; chrony ignores others, and the firewall accepts NTP from these alone. Each item is unique within the list, compared as masked ranges. |
spec.listen |
list of IP address | required | Addresses of the router in the default VRF on which it answers NTP, on UDP port 123; the firewall accepts NTP on them from allow. chrony itself answers on every address, so the firewall alone keeps the others closed. Each item is unique within the list, compared as addresses. |
spec.localStratum |
integer from 1 to 15 or null | null |
Stratum at which the router serves its own clock while it follows no time server, as chrony's local stratum <n> orphan: five minutes after chrony starts without a source, or once the estimated error of the source it followed passes a second, its clients take the router's clock, however far from the real time it is. Null answers as unsynchronised then, which clients refuse. Give a stratum above that of every server on the network, such as 10. |
VRF¶
A VRF of the router: a kernel VRF device of the document's name, its routing table and the links it holds. Other router kinds name it by its name; the default VRF, of every link no VRF holds, has no document.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 5 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.conntrackZone |
integer from 1 to 65535 or null | null |
Conntrack zone of the connections through the VRF's links, which no other VRF uses; null shares zone 0 with the default VRF and every VRF without one. A zone keeps the state and NAT of the VRF's connections apart from those of other VRFs with the same addresses. A VRF with a zone neither imports routes from another VRF nor gives its routes to one. Unique among the VRF documents. |
spec.interfaces |
list of string | [] |
Links the VRF holds, by name or glob, a glob being a prefix followed by *; a glob stands for the links the node's Network documents name in a [Match] section's Name=. A link is named by a Network document, which gets VRF=, and every link of that Network is in this VRF. Each item is unique among the VRF documents. |
spec.table |
integer from 1 to 4294967295 | required | Routing table of the VRF, which no other VRF uses; not 253, 254 or 255, the kernel's tables of the default VRF. A change creates the VRF anew, which ends the sessions in it. Unique among the VRF documents. |
WireGuard¶
A WireGuard interface of the router, named as the document: its UDP port, its addresses, its VRF and the Secret key that holds its private key. Its peers are WireGuardPeer documents.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 4 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.addresses |
list of address range | required | Addresses of the interface with their prefix lengths, as Address= of a Network gives them; the router routes each prefix to the interface. The peers' allowedIPs add routes of their own. Each item is unique within the list. |
spec.listenPort |
integer from 1 to 65535 | 51820 |
UDP port the interface receives its peers' packets on, which the firewall opens in the default VRF. Two WireGuards take different ports. Unique among the WireGuard documents. |
spec.mtu |
integer from 1280 to 9000 or null | null |
MTU of the interface in bytes, from 1280 to 9000; null takes WireGuard's 1420. |
spec.privateKey |
secret reference | required | Key of a Secret that holds the interface's private key, as wg genkey prints it. systemd-networkd reads it from its credentials; no rendered file holds it. The Secret's name and key hold letters, digits, ., _ and - alone. |
spec.vrf |
name of a VRF, or default |
"default" |
VRF document that holds the interface; default for the default VRF. The routes of the peers' allowedIPs go into the VRF's table; the tunnel's own UDP packets travel in the default VRF whatever this says. |
WireGuardPeer¶
A peer of one of the router's WireGuard interfaces: its public key, the address ranges it sends from and the router routes to it, and where the router reaches it.
apiVersion: router.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has a change rule.
| Field | Type | Default | Description |
|---|---|---|---|
spec.allowedIPs |
list of address range | required | Address ranges the router accepts from the peer through the tunnel and sends to it: the router routes each range to the interface in the table of the WireGuard's VRF, a site's networks behind the peer included. The ranges of two peers of one interface do not overlap, and none is a default route, ::/0 or 0.0.0.0/0, which the validator router checks. Each item is unique within the list, compared as masked ranges. |
spec.endpoint |
string or null | null |
Address and UDP port the router sends the peer's first packets to: [<IPv6>]:<port>, <IPv4>:<port> or <host name>:<port>. null waits for the peer to send first, as a laptop behind NAT does; the router then answers where the peer's packets come from. |
spec.interface |
name of a WireGuard | required | WireGuard document of the interface the peer belongs to. |
spec.persistentKeepalive |
integer from 1 to 65535 or null | null |
Seconds between the packets the router sends the peer while the tunnel is idle, which keep a NAT's mapping open; null sends none. |
spec.presharedKey |
secret reference or null | null |
Key of a Secret that holds a key the router and the peer share on top of their key pairs, as wg genpsk prints it; null for none. systemd-networkd reads it from its credentials. The Secret's name and key hold letters, digits, ., _ and - alone. |
spec.publicKey |
string | required | Public key of the peer in base64, as wg pubkey prints it. The validator router refuses a key two peers of one interface have. |
storage.chalkos.dev¶
The kinds of storage.chalkos.dev lay out the node's disks: the system disk and the volumes.
SystemDisk¶
The disk that holds the node's system region and VAR, and the encryption of the node's storage.
apiVersion: storage.chalkos.dev/v1alpha1
A node's config holds at most one. It has a change rule.
| Field | Type | Default | Description |
|---|---|---|---|
spec.disk |
object | required | Disk holding the system region and VAR. |
spec.disk.model |
string or null | null |
Glob the disk's model matches, such as Samsung SSD 870*. |
spec.disk.path |
string or null | null |
Path of the disk below /dev, such as /dev/disk/by-id/…; excludes the selector keys. |
spec.disk.serial |
string or null | null |
The disk's serial number. |
spec.disk.size |
string or null | null |
Comparison the disk's size meets, such as >= 1T; the size has at most 18 digits without a suffix, and 15, 12, 9, 6 or 3 with K, M, G, T or P. |
spec.disk.type |
one of nvme, ssd, hdd or null |
null |
Kind of disk. |
spec.disk.wwn |
string or null | null |
The disk's World Wide Name. |
spec.encryption.fallback |
one of recovery-key, password, none |
"recovery-key" |
Second keyslot asked for on the console when TPM2 unsealing fails. |
spec.encryption.mode |
one of tpm2, none |
"tpm2" |
Encryption of STATE, VAR and volumes: tpm2 seals a LUKS2 key to PCR 7, none uses no encryption. |
spec.var.encryption.mode |
one of tpm2, none or null |
null |
Encryption mode of VAR, over the node's; null takes the node's. |
spec.var.size |
string or null | null |
Size of VAR, such as 20G, with at most 18 digits without a suffix, and 15, 12, 9, 6 or 3 with K, M, G, T or P; null fills the remaining space on the system disk. |
Volume¶
A partition for the node's data, on the system disk or on a disk of its own, which the node creates and mounts.
apiVersion: storage.chalkos.dev/v1alpha1
A node's config may hold several, each with a name of its own. It has 7 change rules.
| Field | Type | Default | Description |
|---|---|---|---|
spec.disk |
object or null | null |
Disk the volume occupies on its own; null places it on the system disk. Unique among the Volume documents by path, model, serial, wwn, size and type. |
spec.disk.model |
string or null | null |
Glob the disk's model matches, such as Samsung SSD 870*. |
spec.disk.path |
string or null | null |
Path of the disk below /dev, such as /dev/disk/by-id/…; excludes the selector keys. |
spec.disk.serial |
string or null | null |
The disk's serial number. |
spec.disk.size |
string or null | null |
Comparison the disk's size meets, such as >= 1T; the size has at most 18 digits without a suffix, and 15, 12, 9, 6 or 3 with K, M, G, T or P. |
spec.disk.type |
one of nvme, ssd, hdd or null |
null |
Kind of disk. |
spec.disk.wwn |
string or null | null |
The disk's World Wide Name. |
spec.encryption.mode |
one of tpm2, none or null |
null |
Encryption mode of the volume, over the node's; null takes the node's. |
spec.format |
one of ext4, xfs, btrfs, swap, raw |
"ext4" |
File system of the volume; raw leaves a raw block device, which has no mountPoint. |
spec.mountPoint |
string or null | null |
Where the volume is mounted; null leaves it unmounted. Unique among the Volume documents. |
spec.repart |
map of string | {} |
Extra repart.d keys of the volume's partition. Type, Label, Encrypt, Format, SizeMinBytes, SizeMaxBytes and MountPoint come from the typed options. |
spec.size |
string or null | null |
Size of the volume, such as 100G, with at most 18 digits without a suffix, and 15, 12, 9, 6 or 3 with K, M, G, T or P; null fills the remaining space on its disk. |
time.chalkos.dev¶
The kinds of time.chalkos.dev set how the node synchronises its clock.
TimeSync¶
The time servers the node synchronises its clock with.
apiVersion: time.chalkos.dev/v1alpha1
A node's config holds at most one.
| Field | Type | Default | Description |
|---|---|---|---|
spec.dhcp |
boolean | false |
Whether the node also synchronises with the time servers the network announces through DHCP, which are not authenticated. |
spec.servers |
list of object | [{"host":"ptbtime1.ptb.de"},{"host":"ptbtime2.ptb.de"},{"host":"ptbtime3.ptb.de"}] |
Time servers the node synchronises its clock with, authenticated with NTS unless nts = false. |
spec.servers[].host |
string | required | Host name or address of the time server. |
spec.servers[].nts |
boolean | true |
Whether the node authenticates the server with Network Time Security (NTS). |
spec.servers[].port |
integer from 0 to 65535 or null | null |
UDP port of the server's NTP; null is NTP's port, 123. |
Inventory and lab files¶
chalkctl reads an inventory and chalklab a lab file. Neither is part of a node's config.
Inventory¶
The nodes of a cluster, where chalkctl reaches each, the image each runs and the config files each gets. Paths are relative to the inventory's directory, and file lists take globs.
apiVersion: chalkctl.chalkos.dev/v1alpha1
| Field | Type | Default | Description |
|---|---|---|---|
spec.all |
object | — | What every node gets: the image of the nodes that name none and whose groups name none, and the config files every node gets first. |
spec.all.files |
list of string | — | Config files the nodes under it get. |
spec.all.imageName |
string | — | The image of the nodes under it that name none of their own. |
spec.groups |
map of object | — | Groups of nodes by name, which a node joins by naming them in its groups. |
spec.groups.<name>.files |
list of string | — | Config files the nodes under it get. |
spec.groups.<name>.imageName |
string | — | The image of the nodes under it that name none of their own. |
spec.images |
map of object | — | The images the nodes run, by name. |
spec.images.<name>.source |
object | required | Where the image comes from: exactly one of directory and oci. |
spec.images.<name>.source.directory |
string | — | Directory of an image build as nix build makes it, holding its metadata.json; a relative directory is relative to the inventory's directory. |
spec.images.<name>.source.oci |
string | — | Reference of the image in an OCI registry, naming the registry and a tag or a digest, such as ghcr.io/example/node-metal:v1 or the repository@sha256:… chalkbuild push prints. chalkctl resolves a tag to its digest once per command and reads the image's header and contract layer with the credentials of docker's config; an upgrade, and an install on a node that runs the installer, have the node pull the image by that digest. |
spec.nodes |
map of object | — | The cluster's nodes by name. A node's name is fixed at install, which writes it into the node's certificate; its hostname defaults to it, and the Kubernetes node name, the storage seeds and the recovery key derive from it, so renaming a node takes a reinstall. |
spec.nodes.<name>.address |
string | — | Where chalkctl reaches the node's chalkd: a host or host:port. |
spec.nodes.<name>.files |
list of string | — | The node's own config files. |
spec.nodes.<name>.groups |
list of string | — | Groups whose files the node gets, in this order; the node runs their image unless it names its own. |
spec.nodes.<name>.imageName |
string | — | The image the node runs, over that of its groups and spec.all.imageName. |
Lab¶
The nodes of an inventory that chalklab runs as virtual machines, and their machines.
apiVersion: chalklab.chalkos.dev/v1alpha1
| Field | Type | Default | Description |
|---|---|---|---|
spec.inventory |
string | required | The inventory of the cluster, relative to the lab file. |
spec.nodes |
map of object | required | The VMs of the lab by the names of their nodes in the inventory. |
spec.nodes.<name>.cpus |
integer of at least 1 | 2 |
Number of the VM's virtual CPUs. |
spec.nodes.<name>.disks |
list of object | [{"size":"16G"}] |
The VM's disks: the first holds the node's image, the others start empty. |
spec.nodes.<name>.disks[].serial |
string | — | Serial number the disk reports to the node, up to 20 letters, digits, _ and -, for a SystemDisk or Volume to select it by. |
spec.nodes.<name>.disks[].size |
string | required | Size of the disk in bytes, or with a K, M, G or T suffix, such as 16G. |
spec.nodes.<name>.forwards |
list of integer from 1 to 65535 | — | TCP ports of the node that the host reaches at a free port on 127.0.0.1 each, which chalklab status lists. The node's chalkd and a control plane's API server have theirs anyway. |
spec.nodes.<name>.mac |
string | required | MAC address of the VM's NIC on the lab network, which the node's Network document must match. |
spec.nodes.<name>.memory |
integer of at least 512 | — | Memory of the VM in MiB; without it, 3072 for a control plane and 2048 for another node. |
Sources: the JSON Schemas in the schemas directory of an image
build with the Kubernetes layer and of a
router image, from modules/node/kinds/builtin/, modules/node/kubernetes/kinds.nix, the
kinds.nix files of modules/node/router/ and the tables of the image's systemd-networkd, and
pkg/inventory/chalkctl.chalkos.dev_v1alpha1_Inventory.json and
pkg/chalklab/chalklab.chalkos.dev_v1alpha1_Lab.json.