From 6ab6524c5beac7f6028f5f186d91f6be306394bf Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:18:07 -0500 Subject: [PATCH 01/27] Modernize repository index and maintenance guidance --- README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 90 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 83ee0ca..4a392ec 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,101 @@ -# Cheatsheets Repository +# Infrastructure and Network Engineering Cheatsheets -Welcome to the Cheatsheets Repository – your one-stop hub for quick-reference guides in the world of networking and technology. This repository is dedicated to providing concise, easy-to-understand cheat sheets for a range of technologies including Cisco, Juniper, Arista, and more. +Practical quick-reference notes for network engineering, Linux operations, cloud platforms, infrastructure automation, and troubleshooting. ---- +> [!WARNING] +> These notes are a memory aid, not a substitute for vendor documentation, change review, backups, or a tested rollback plan. Commands that alter state can cause outages or data loss. Validate syntax against the exact software and platform release you operate. -**Key Features:** +## How to use this repository -- **Comprehensive Coverage:** From basic commands to advanced configurations, our cheat sheets span a wide array of topics and technologies. -- **User-Friendly Format:** Designed for both beginners and seasoned professionals, these cheat sheets are structured to provide information at a glance. -- **Regular Updates:** The tech world is always evolving, and so are our cheat sheets. Stay up-to-date with the latest commands and functionalities. -- **Community-Driven:** Contributions are welcome! Help us expand and refine our cheat sheets to cover more technologies and topics. +- Replace values such as ``, ``, and `` before running commands. +- Start with read-only inspection commands and capture the current state. +- Treat `clear`, `delete`, `destroy`, `flush`, `reset`, `prune`, and `--force` operations as destructive. +- Prefer official documentation for release-specific behavior. +- Open a content-correction issue when a command is obsolete, unsafe, ambiguous, or vendor-specific. -**Ideal For:** +## Networking fundamentals -- Network Engineers and IT Professionals seeking quick references. -- Students and educators in the field of Information Technology and Computer Science. -- Anyone looking to expand their knowledge in networking technologies. +| Topic | Reference | +|---|---| +| Clos fabrics | [clos.md](clos.md) | +| Leaf-spine design | [leafspine.md](leafspine.md) | +| LLDP | [lldp.md](lldp.md) | +| OSI model | [osi.md](osi.md) | +| OSPF | [ospf.md](ospf.md) | +| TCP | [tcp.md](tcp.md) | +| UDP | [udp.md](udp.md) | +| QUIC, MASQUE, and SRv6 | [quic-masque-srv6.md](quic-masque-srv6.md) | -**Get Involved:** +## Network platforms and routing software -We encourage you to contribute and share your expertise. Whether it's fixing a typo, adding a new cheat sheet, or improving existing content, every bit of help is appreciated! +| Platform | Reference | +|---|---| +| Arista EOS | [arista.md](arista.md) | +| BIRD | [bird.md](bird.md) | +| Cisco IOS / IOS XE | [cisco.md](cisco.md) | +| Fortinet FortiGate | [fortinet.md](fortinet.md) | +| Juniper Junos | [juniper.md](juniper.md) | -**Navigate with Ease:** +## Cisco contact center -Our repository is organized for easy navigation, allowing you to quickly find the cheat sheet you need. Whether you're configuring a Cisco router, setting up a Juniper network, or exploring Arista technologies, the right information is just a click away. +| Product | Reference | +|---|---| +| Cisco Unified Intelligence Center | [cisco-cuic.md](cisco-cuic.md) | +| Cisco Unified Customer Voice Portal | [cisco-cvp.md](cisco-cvp.md) | +| Cisco Intelligent Contact Management | [cisco-icm.md](cisco-icm.md) | -**Join us in building the most comprehensive and user-friendly tech cheat sheets collection. Star, fork, and contribute today!** +## Cloud platforms + +| Topic | Reference | +|---|---| +| AWS services | [awscloud.md](awscloud.md) | +| AWS CLI | [awscli.md](awscli.md) | +| Microsoft Azure and Azure CLI | [azure.md](azure.md) | +| Google Cloud services | [gcpcloud.md](gcpcloud.md) | +| Google Cloud CLI | [gcloud.md](gcloud.md) | + +## Containers, orchestration, and infrastructure as code + +| Topic | Reference | +|---|---| +| Docker and Docker Compose | [docker.md](docker.md) | +| Kubernetes and kubectl | [kubernetes.md](kubernetes.md) | +| Terraform | [terraform.md](terraform.md) | +| Jenkins CI/CD | [jenkins-cicd.md](jenkins-cicd.md) | +| Puppet | [puppet.md](puppet.md) | + +## Linux and operations + +| Topic | Reference | +|---|---| +| awk | [awk.md](awk.md) | +| Debian | [debian.md](debian.md) | +| HAProxy | [haproxy.md](haproxy.md) | +| iptables | [iptables.md](iptables.md) | +| Linux boot process | [linux_kernel_boot.md](linux_kernel_boot.md) | +| nmap | [nmap.md](nmap.md) | +| Pacemaker | [pacemaker.md](pacemaker.md) | +| Corosync | [corosync.md](corosync.md) | +| Regular expressions | [regex.md](regex.md) | +| SCP | [scp.md](scp.md) | +| sed | [sed.md](sed.md) | +| Xen | [xen.md](xen.md) | + +## Development and data + +| Topic | Reference | +|---|---| +| Git | [git.md](git.md) | +| Kafka | [kafka.md](kafka.md) | +| REST APIs | [rest-api.md](rest-api.md) | +| SQL | [sql.md](sql.md) | + +## Maintenance policy + +Accuracy-sensitive documents should include an **Applies to** line and a **Last reviewed** date. A review date means the examples received a documentation review; it does not guarantee compatibility with every release or environment. + +Repository quality checks validate Markdown and links on pull requests and changes to `main`. See [CONTRIBUTING.md](CONTRIBUTING.md) and [STYLE_GUIDE.md](STYLE_GUIDE.md) before adding or substantially rewriting a sheet. + +## License + +Content is available under the [MIT License](LICENSE). \ No newline at end of file From 20681c85fe3269667a873ee6d91f5ec7b4cf1c19 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:18:19 -0500 Subject: [PATCH 02/27] Add contribution guidance --- CONTRIBUTING.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c6fdce2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,61 @@ +# Contributing + +Corrections and focused additions are welcome. The goal is operationally useful, concise, and verifiable reference material. + +## Before submitting a change + +1. Verify commands against official vendor or project documentation. +2. State the platform, operating system, or major release when syntax is version-sensitive. +3. Test examples in a lab or disposable environment when practical. +4. Mark destructive commands clearly and include a safer inspection step first. +5. Never commit real credentials, internal addresses, customer data, private architecture, or employer-specific interview material. + +## Cheat-sheet structure + +Use the following order when it fits the topic: + +```markdown +# Product or Topic Cheat Sheet + +> **Applies to:** Product family or major release +> **Last reviewed:** YYYY-MM-DD + +A one-paragraph scope statement. + +## Safety + +Important operational warnings. + +## Quick reference + +Commands and concise explanations. + +## Troubleshooting workflow + +A read-only, least-disruptive-first sequence. + +## Official references + +- [Documentation title](https://example.com) +``` + +## Style rules + +- Use one `#` heading per document. +- Use fenced code blocks with a language identifier when possible. +- Use placeholders in angle brackets, such as `` or ``. +- Prefer tables for compact command references. +- Explain important side effects directly beside the command. +- Avoid marketing language such as “comprehensive,” “ultimate,” or “one-stop.” +- Keep conceptual overviews separate from command references when either becomes long. + +## Pull requests + +A pull request should explain: + +- what changed; +- why the previous content was inaccurate or difficult to use; +- which official references were used; +- how the examples were validated. + +For a simple typo or broken link, a short explanation is sufficient. \ No newline at end of file From e877f3496400781337afb3aedb647e21bde4f0ad Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:18:32 -0500 Subject: [PATCH 03/27] Add documentation style guide --- STYLE_GUIDE.md | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 STYLE_GUIDE.md diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md new file mode 100644 index 0000000..b9fdcba --- /dev/null +++ b/STYLE_GUIDE.md @@ -0,0 +1,53 @@ +# Documentation Style Guide + +## Purpose + +Each file should help an engineer answer a specific operational question quickly. Prefer commands, decision points, expected output, and cautions over broad product descriptions. + +## Required metadata for maintained sheets + +Place these lines immediately below the title: + +```markdown +> **Applies to:** Product family or major release +> **Last reviewed:** YYYY-MM-DD +``` + +Use `General concepts` when the material is standards-based rather than tied to one implementation. + +## Command presentation + +Use angle-bracket placeholders: + +```bash +show interface +kubectl get pods --namespace +``` + +Do not use realistic credentials, public IP addresses belonging to third parties, internal hostnames, or customer-specific identifiers. + +For state-changing commands, show a read-only verification command first and add an inline warning when the operation is destructive. + +## Troubleshooting order + +Troubleshooting sections should generally proceed in this order: + +1. confirm scope and symptoms; +2. inspect state without changing it; +3. collect logs, counters, and timestamps; +4. compare intended and actual configuration; +5. apply the least disruptive correction; +6. verify service recovery; +7. document the change and rollback state. + +## Terminology + +- Use current product names and mention former names only when useful for searchability. +- Distinguish a protocol standard from a vendor implementation. +- Do not imply a command is portable across vendors or releases when it is not. +- Use “data center” as two words in prose. +- Expand an acronym on first use unless it is universally understood in the document’s audience. + +## References + +Prefer official project documentation, standards documents, vendor command references, and RFCs. Avoid copying large passages. Link to the authoritative source and summarize the operational implication. \ No newline at end of file From 60fc4c5d81e0c18be988f52755b0709264eb13e4 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:18:43 -0500 Subject: [PATCH 04/27] Add MIT license --- LICENSE | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..cf2ced6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Antonio Flores + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file From f58164b614cd06933e6c3761a0c61938a1226912 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:18:49 -0500 Subject: [PATCH 05/27] Configure Markdown linting --- .markdownlint.json | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 .markdownlint.json diff --git a/.markdownlint.json b/.markdownlint.json new file mode 100644 index 0000000..5a092df --- /dev/null +++ b/.markdownlint.json @@ -0,0 +1,8 @@ +{ + "default": true, + "MD013": false, + "MD024": false, + "MD033": false, + "MD036": false, + "MD041": true +} From 9870c8806374937fd5ad524a3da39bef30a03927 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:18:55 -0500 Subject: [PATCH 06/27] Add documentation quality checks --- .github/workflows/docs-quality.yml | 36 ++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 .github/workflows/docs-quality.yml diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml new file mode 100644 index 0000000..1e165cf --- /dev/null +++ b/.github/workflows/docs-quality.yml @@ -0,0 +1,36 @@ +name: Documentation quality + +on: + pull_request: + push: + branches: + - main + workflow_dispatch: + +permissions: + contents: read + +jobs: + markdownlint: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Lint Markdown + uses: DavidAnson/markdownlint-cli2-action@v20 + with: + globs: | + **/*.md + + links: + runs-on: ubuntu-latest + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Check links + uses: lycheeverse/lychee-action@v2 + with: + args: --verbose --no-progress './**/*.md' + fail: true From c7af122b1f1bda1d8393e4677c06ccb0c7f00f6f Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:19:04 -0500 Subject: [PATCH 07/27] Add content correction issue template --- .github/ISSUE_TEMPLATE/content-correction.yml | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/content-correction.yml diff --git a/.github/ISSUE_TEMPLATE/content-correction.yml b/.github/ISSUE_TEMPLATE/content-correction.yml new file mode 100644 index 0000000..cf87902 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/content-correction.yml @@ -0,0 +1,40 @@ +name: Content correction +description: Report an inaccurate, obsolete, unsafe, or unclear command or explanation +title: "[Correction]: " +labels: + - documentation +body: + - type: input + id: file + attributes: + label: File + description: Which cheat sheet needs correction? + placeholder: docker.md + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem + description: Explain what is inaccurate, obsolete, unsafe, or unclear. + validations: + required: true + + - type: input + id: platform + attributes: + label: Platform and version + description: Include the product, operating system, and version when relevant. + + - type: textarea + id: correction + attributes: + label: Suggested correction + description: Provide corrected wording or commands when possible. + + - type: textarea + id: references + attributes: + label: Official references + description: Link the relevant vendor, project, or standards documentation. From 98a22811f4c3b9db517b688450dff4a8e35add27 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:19:28 -0500 Subject: [PATCH 08/27] Modernize Docker and Compose reference --- docker.md | 216 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 146 insertions(+), 70 deletions(-) diff --git a/docker.md b/docker.md index 7b111de..7256d61 100644 --- a/docker.md +++ b/docker.md @@ -1,108 +1,184 @@ -# Docker Command Cheat Sheet +# Docker and Docker Compose Cheat Sheet -This cheat sheet is intended for developers, DevOps engineers, and system administrators who use Docker for containerization. Docker is a popular platform for developing, shipping, and running applications in isolated environments called containers. +> **Applies to:** Current Docker Engine and Docker Compose v2 +> **Last reviewed:** 2026-07-14 -The commands listed here provide a comprehensive guide for managing Docker containers, images, volumes, networks, and more. This guide aims to streamline Docker operations and offer quick access to common commands necessary for effective container management and deployment. -Docker Commands +A quick reference for inspecting and operating containers, images, networks, volumes, and Compose applications. -## Container Management +## Safety -- **docker run [options] [image] [command]** - - Runs a command in a new container. +> [!WARNING] +> `rm`, `prune`, and Compose commands using `--volumes` can permanently remove containers or data. Inspect the target first and verify backups before deleting named volumes. -- **docker ps** - - Lists running containers. +## Environment and status -- **docker ps -a** - - Lists all containers, including stopped ones. +```bash +docker version +docker info +docker context show +docker system df +``` -- **docker stop [container]** - - Stops a running container. +## Containers -- **docker start [container]** - - Starts a stopped container. +```bash +# List containers +docker ps +docker ps --all -- **docker restart [container]** - - Restarts a container. +# Run a disposable interactive container +docker run --rm -it -- **docker rm [container]** - - Removes a container. +# Start, stop, and restart +docker start +docker stop +docker restart -- **docker logs [container]** - - Fetches logs of a container. +# Inspect state and resource use +docker inspect +docker stats +docker top -## Image Management +# Logs +docker logs --tail 100 +docker logs --follow --since 10m -- **docker images** - - Lists all downloaded images. +# Execute a command in a running container +docker exec -it -- **docker pull [image]** - - Pulls an image from a registry. +# Copy files +docker cp : +docker cp : +``` -- **docker push [image]** - - Pushes an image to a registry. +Remove a stopped container only after checking it: -- **docker rmi [image]** - - Removes an image. +```bash +docker inspect +docker rm +``` -- **docker build -t [tag] .** - - Builds an image from a Dockerfile in the current directory. +## Images -## Container Operations +```bash +docker image ls +docker pull : +docker image inspect : +docker build --tag : . +docker tag /: +docker push /: +docker image history : +``` -- **docker exec -it [container] [command]** - - Executes a command in a running container. +Remove an image: -- **docker attach [container]** - - Attaches to a running container. +```bash +docker image rm : +``` -- **docker cp [container]:[path] [local_path]** - - Copies files from a container to the local filesystem. +## Networks -- **docker rename [old_container_name] [new_container_name]** - - Renames a container. +```bash +docker network ls +docker network inspect +docker network create +docker network connect +docker network disconnect +docker port +``` -## Network Management +## Volumes -- **docker network ls** - - Lists networks. +```bash +docker volume ls +docker volume inspect +docker volume create +``` -- **docker network create [options] [network]** - - Creates a new network. +Before removing a volume, confirm that no container needs its data: -- **docker network rm [network]** - - Removes a network. +```bash +docker ps --all --filter volume= +docker volume rm +``` -- **docker network connect [network] [container]** - - Connects a container to a network. +## Docker Compose v2 -- **docker network disconnect [network] [container]** - - Disconnects a container from a network. +Compose v2 uses the integrated `docker compose` command. The older `docker-compose` executable is legacy syntax. -## Volume and Storage +```bash +# Validate and render the effective configuration +docker compose config -- **docker volume ls** - - Lists all volumes. +# Start services +docker compose up --detach -- **docker volume create [volume]** - - Creates a new volume. +# Show service state +docker compose ps -- **docker volume rm [volume]** - - Removes a volume. +# Follow logs +docker compose logs --follow --tail 100 -- **docker volume inspect [volume]** - - Inspects a volume. +# Execute a command in a service container +docker compose exec -## Docker Compose +# Pull and rebuild +docker compose pull +docker compose build --pull -- **docker-compose up** - - Starts and runs the entire app defined in `docker-compose.yml`. +# Restart one service +docker compose restart -- **docker-compose down** - - Stops and removes containers, networks, images, and volumes. +# Stop services without removing containers +docker compose stop -- **docker-compose build** - - Builds or rebuilds services. +# Remove Compose containers and default networks +docker compose down +``` -- **docker-compose logs [service]** - - View output from containers. +`docker compose down` does **not** remove named volumes or images by default. Destructive variants must be explicit: + +```bash +# Also remove named and anonymous volumes +docker compose down --volumes + +# Also remove images created or used by the project +docker compose down --rmi local +``` + +## Cleanup + +Preview disk usage first: + +```bash +docker system df --verbose +docker container prune --filter until=24h +docker image prune +docker volume prune +``` + +> [!CAUTION] +> `docker system prune --all --volumes` can remove unused images and volumes containing data. Do not use it as routine housekeeping without reviewing the impact. + +## Troubleshooting workflow + +```bash +docker ps --all +docker inspect +docker logs --tail 200 +docker stats --no-stream +docker network inspect +docker events --since 10m +``` + +Check the container exit code and health status: + +```bash +docker inspect --format '{{.State.Status}} exit={{.State.ExitCode}} health={{if .State.Health}}{{.State.Health.Status}}{{end}}' +``` + +## Official references + +- [Docker command-line reference](https://docs.docker.com/reference/cli/docker/) +- [Docker Compose command-line reference](https://docs.docker.com/reference/cli/docker/compose/) +- [docker compose down](https://docs.docker.com/reference/cli/docker/compose/down/) \ No newline at end of file From ac7eebf22bdae6298d8a0f79307da240931ff334 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:19:47 -0500 Subject: [PATCH 09/27] Modernize Terraform command reference --- terraform.md | 195 ++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 154 insertions(+), 41 deletions(-) diff --git a/terraform.md b/terraform.md index 52209c0..37506c7 100644 --- a/terraform.md +++ b/terraform.md @@ -1,64 +1,177 @@ -# Terraform Command Cheat Sheet +# Terraform CLI Cheat Sheet -This cheat sheet is designed for DevOps engineers, cloud architects, and anyone who uses Terraform for infrastructure as code. Terraform, by HashiCorp, is an immensely popular tool for building, changing, and versioning infrastructure safely and efficiently. +> **Applies to:** Terraform 1.x +> **Last reviewed:** 2026-07-14 + +A quick reference for formatting, validating, planning, applying, inspecting, and carefully repairing Terraform-managed infrastructure. -The commands listed here range from basic setup and initialization to more advanced infrastructure management. This guide serves as a quick reference to essential Terraform commands, facilitating efficient infrastructure deployment and management. -Terraform Commands +## Safety -## Setup and Initialization +> [!WARNING] +> Review every plan before applying it. State commands can change Terraform’s record without changing real infrastructure. Back up remote state and confirm locking before manual state repair. -- **terraform init** - - Initializes a new or existing Terraform configuration. +## Daily workflow -- **terraform version** - - Displays the current Terraform version. +```bash +terraform version +terraform fmt --recursive +terraform init +terraform validate +terraform plan -out=tfplan +terraform show tfplan +terraform apply tfplan +``` -- **terraform validate** - - Validates the Terraform files in a directory. +Use a saved plan when the reviewed plan must be exactly the one applied. Never commit plan files because they can contain sensitive values. -## Plan and Apply +## Initialization and providers -- **terraform plan** - - Creates an execution plan. +```bash +terraform init +terraform init -upgrade +terraform providers +terraform providers schema -json +terraform providers lock \ + -platform=linux_amd64 \ + -platform=darwin_arm64 +``` -- **terraform apply** - - Applies the changes required to reach the desired state of the configuration. +Commit `.terraform.lock.hcl`. Do not commit `.terraform/`. -- **terraform apply "planfile"** - - Applies the changes in a Terraform plan file. +## Planning -## State Management +```bash +terraform plan +terraform plan -out=tfplan +terraform plan -refresh-only +terraform plan -destroy +terraform plan -var-file=.tfvars +terraform plan -target= +``` -- **terraform state list** - - Lists resources in the state file. +> [!CAUTION] +> `-target` is intended for exceptional recovery or focused troubleshooting. Re-run a full plan afterward to detect remaining drift. -- **terraform state show [resource]** - - Shows the attributes of a resource in the state file. +## Applying and destroying -- **terraform state rm [resource]** - - Removes a resource from the state file. +```bash +terraform apply +terraform apply tfplan +terraform apply -refresh-only +terraform destroy +``` -## Workspace Management +Avoid `-auto-approve` in interactive production workflows unless a reviewed automation pipeline controls the inputs and plan. -- **terraform workspace list** - - Lists all existing workspaces. +## Outputs and inspection -- **terraform workspace new [name]** - - Creates a new workspace. +```bash +terraform output +terraform output -json +terraform show +terraform show -json tfplan +terraform console +terraform graph +``` -- **terraform workspace select [name]** - - Selects an existing workspace. +## Workspaces -## Misc Commands +```bash +terraform workspace show +terraform workspace list +terraform workspace new +terraform workspace select +terraform workspace delete +``` -- **terraform import [resource.address] [id]** - - Imports existing infrastructure into Terraform. +CLI workspaces share a backend and configuration. They are not a complete isolation boundary for environments with different credentials, policies, or blast radii. -- **terraform taint [resource]** - - Marks a resource for recreation on the next apply. +## State inspection and repair -- **terraform untaint [resource]** - - Removes the 'taint' from a resource. +```bash +terraform state list +terraform state show +terraform state pull > state-backup.json +terraform state mv +terraform state rm +``` -- **terraform graph** - - Generates a visual representation of either a configuration or execution plan. +Before a manual state change: + +1. stop concurrent runs; +2. confirm state locking; +3. save a state backup; +4. document the intended mapping; +5. run a full plan afterward. + +## Import existing infrastructure + +Terraform supports import blocks in configuration: + +```hcl +import { + to = + id = "" +} +``` + +Then run: + +```bash +terraform plan +``` + +The legacy CLI form is still available: + +```bash +terraform import +``` + +Import adds an object to state; it does not automatically produce a complete, maintainable configuration. + +## Replace a resource + +Prefer a reviewable plan using `-replace`: + +```bash +terraform plan -replace= -out=tfplan +terraform apply tfplan +``` + +`terraform taint` is deprecated. Do not teach it as the normal replacement workflow. + +## Dependency and configuration troubleshooting + +```bash +terraform fmt -check -recursive +terraform validate +terraform providers +terraform state list +terraform plan -refresh-only +TF_LOG=DEBUG terraform plan +``` + +Debug logs can contain sensitive values. Store and share them carefully, then unset logging: + +```bash +unset TF_LOG +unset TF_LOG_PATH +``` + +## Locked state + +Investigate the active lock owner before using: + +```bash +terraform force-unlock +``` + +> [!DANGER] +> Forcing an active lock can allow concurrent state writes and corrupt state. Use it only after proving that the locking process is gone. + +## Official references + +- [Terraform CLI documentation](https://developer.hashicorp.com/terraform/cli) +- [Terraform state commands](https://developer.hashicorp.com/terraform/cli/commands/state) +- [Replace resources](https://developer.hashicorp.com/terraform/cli/state/taint) +- [Import existing resources](https://developer.hashicorp.com/terraform/language/import) \ No newline at end of file From 91ff4f7c7035add24f54c4e6618a57628f980528 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:20:10 -0500 Subject: [PATCH 10/27] Correct and modernize Cisco IOS reference --- cisco.md | 394 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 198 insertions(+), 196 deletions(-) diff --git a/cisco.md b/cisco.md index 1b67450..5adac06 100644 --- a/cisco.md +++ b/cisco.md @@ -1,196 +1,198 @@ -# Cisco Command Cheat Sheet - -This document is a curated collection of essential Cisco commands for network and systems engineers. It focuses on troubleshooting Layer 2 issues and general network management on Cisco devices. These commands are vital for diagnosing connectivity problems, VLAN configurations, STP issues, and more. - -The cheat sheet is designed as a quick reference to facilitate daily network management tasks and to assist in rapidly resolving common network issues. Please use these commands with caution, as they can significantly impact network operations, especially in a production environment. - -## Interface Management and Status - -- **show interfaces** - - Displays status and statistics for all interfaces. - -- **show interfaces [interface]** - - Shows detailed information about a specific interface. - -- **show interfaces status** - - Provides a quick overview of all interfaces' status. - -- **show interface [INTERFACE_NAME] switchport** - - Displays switchport information for a specific interface. - -- **show interface [INTERFACE_NAME] status** - - Shows the status of a specific interface. - -- **show interface [INTERFACE_NAME] counters** - - Shows detailed counters for a specific interface. - -- **show interface counters errors** - - Displays interface error counters. - -- **show interfaces description** - - Displays interface descriptions and status. - -- **test cable-diagnostics tdr interface [INTERFACE_NAME]** - - Runs a Time Domain Reflectometer (TDR) test on a specified interface. - - -## VLAN and Trunking - -- **show vlan** - - Displays VLAN information. - -- **show vlan brief** - - Provides a brief summary of all VLANs. - -- **vlan [VLAN_ID]** - - Creates a VLAN or enters VLAN configuration mode. - -- **show interfaces trunk** - - Displays trunk ports and their encapsulation. - -- **switchport mode access** - - Sets an interface to access mode. - -- **switchport mode trunk** - - Sets an interface to trunk mode. - -- **switchport access vlan [VLAN_ID]** - - Assigns an access VLAN to an interface. - -- **switchport trunk allowed vlan [VLAN_LIST]** - - Specifies VLANs allowed on a trunk interface. - -## Spanning Tree Protocol (STP) - -- **show spanning-tree** - - Displays Spanning Tree Protocol (STP) information. - -- **show spanning-tree summary** - - Shows a summary of STP status. - -- **show spanning-tree root** - - Displays the root bridge information for STP. - -- **show spanning-tree [vlan VLAN_ID]** - - Shows STP information for a specific VLAN. - -- **debug spanning-tree events** - - Enables debugging for STP events. - -## EtherChannel and Port Security - -- **show etherchannel summary** - - Provides a summary of EtherChannel status. - -- **channel-group [NUMBER] mode active** - - Configures an interface to actively form an EtherChannel. - -- **show port-security** - - Displays port security settings. - -- **show port-security interface [interface]** - - Shows port security details on a specific interface. - -## Discovery Protocols and Environmental Information - -- **show cdp neighbors** - - Lists Cisco Discovery Protocol (CDP) neighbor devices. - -- **show cdp neighbors detail** - - Provides detailed information about CDP neighbors. - -- **show lldp neighbors** - - Lists Link Layer Discovery Protocol (LLDP) neighbor devices. - -- **show lldp neighbors detail** - - Provides detailed information about LLDP neighbors. - -- **show environment** - - Displays environmental information like temperature and power supply status. - -## System Information and Configuration - -- **show version** - - Displays system hardware and software status. - -- **show inventory** - - Shows hardware inventory details. - -- **show running-config interface [INTERFACE_NAME]** - - Shows the running configuration of a specific interface. - -- **show ip interface brief** - - Summarizes IP interface status and configuration. - -- **show processes cpu** - - Shows CPU utilization. - -- **show processes memory** - - Displays memory usage. - -- **show logging** - - Displays the system log for potential error messages or alerts. - -- **copy running-config startup-config** - - Saves the current configuration to the startup configuration. - -- **show boot** - - Shows boot path and image information. - -- **show flash:** - - Displays the contents of the flash memory. - -## MAC Address Table and ARP - -- **show mac address-table** - - Displays the MAC address table. - -- **show mac address-table dynamic** - - Shows dynamically learned MAC addresses. - -- **show arp** - - Shows the ARP table. - -- **clear mac address-table dynamic** - - Clears the dynamic entries from the MAC address table. - -## Miscellaneous Commands - -- **show vtp status** - - Displays VLAN Trunking Protocol (VTP) status. - -- **show udld [INTERFACE_NAME]** - - Shows UniDirectional Link Detection (UDLD) status on an interface. - -- **clear counters [interface]** - - Clears the counters on a specific interface. - -- **show sdm prefer** - - Shows the Switch Database Management (SDM) template in use. - -- **show standby** - - Displays Hot Standby Router Protocol (HSRP) information. - -- **show access-lists** - - Displays configured access lists. - -- **show power inline** - - Shows Power over Ethernet (PoE) status on interfaces. - -- **show redundancy** - - Displays redundancy information (useful in MLAG setups). - -- **show vrf** - - Displays VRF (Virtual Routing and Forwarding) information. - -- **show mlag** - - Displays MLAG configuration and status. - -- **mlag peer** - - Configures MLAG peer settings. - -- **mlag domain** - - Configures an MLAG domain. - -- **show mlag detail** - - Provides detailed information about MLAG status. +# Cisco IOS and IOS XE Cheat Sheet + +> **Applies to:** Common Cisco IOS and IOS XE switching and routing workflows +> **Last reviewed:** 2026-07-14 + +Command availability and output vary by platform and release. This sheet intentionally excludes Arista EOS MLAG syntax and NX-OS-only commands. + +## Safety + +> [!WARNING] +> Debugging, clearing protocol sessions, changing trunk VLANs, and modifying spanning-tree settings can interrupt production traffic. Capture the current state and confirm a rollback method first. + +## Device and system state + +```text +show version +show inventory +show running-config +show startup-config +show logging +show clock +show processes cpu sorted +show processes memory sorted +show environment all +show redundancy +show boot +show file systems +show flash: +``` + +## Interfaces + +```text +show interfaces status +show interfaces description +show ip interface brief +show interfaces +show interfaces switchport +show interfaces counters errors +show interfaces counters errors +show running-config interface +show controllers ethernet-controller phy +``` + +Cable diagnostics are platform-dependent: + +```text +test cable-diagnostics tdr interface +show cable-diagnostics tdr interface +``` + +Clear counters only when you have recorded the previous values: + +```text +clear counters +``` + +## VLANs and trunks + +```text +show vlan brief +show interfaces trunk +show interfaces switchport +show spanning-tree vlan +``` + +Example access port: + +```text +interface + description + switchport + switchport mode access + switchport access vlan + spanning-tree portfast + spanning-tree bpduguard enable +``` + +Example trunk: + +```text +interface + description + switchport + switchport mode trunk + switchport trunk allowed vlan +``` + +> [!CAUTION] +> `switchport trunk allowed vlan ` replaces the effective allowed list in many workflows. Use `add` or `remove` only when that is the intended change, and verify with `show interfaces trunk`. + +## Spanning Tree Protocol + +```text +show spanning-tree summary +show spanning-tree root +show spanning-tree vlan +show spanning-tree interface detail +show spanning-tree inconsistentports +``` + +Avoid broad debugging in production. If debugging is required, constrain it and disable it immediately afterward: + +```text +show debugging +undebug all +``` + +## EtherChannel and LACP + +```text +show etherchannel summary +show etherchannel port-channel +show lacp neighbor +show lacp counters +show interfaces port-channel +``` + +Example LACP bundle: + +```text +interface range + channel-group mode active + +interface port-channel + description +``` + +## MAC, ARP, and neighbors + +```text +show mac address-table +show mac address-table dynamic +show mac address-table interface +show arp +show ip arp +show cdp neighbors detail +show lldp neighbors detail +``` + +Clear dynamic MAC entries only for a confirmed troubleshooting need: + +```text +clear mac address-table dynamic interface +``` + +## Layer 3 and routing + +```text +show ip route +show ip route +show ip protocols +show ip cef detail +show ip interface +show access-lists +show ip access-lists +show vrf +show ip route vrf +``` + +## First-hop redundancy + +```text +show standby brief +show standby +show vrrp brief +``` + +## Power over Ethernet + +```text +show power inline +show power inline detail +``` + +## Configuration handling + +```text +show archive config differences nvram:startup-config system:running-config +copy running-config startup-config +``` + +Before a risky remote change, use a rollback-capable workflow supported by the platform, such as configuration archive and `reload in`, and confirm the exact behavior in the device documentation. + +## Troubleshooting workflow + +1. Confirm scope: one endpoint, one VLAN, one interface, or a wider failure. +2. Check interface state and counters. +3. Validate VLAN, trunk, and spanning-tree state. +4. Confirm MAC learning, ARP, and neighbor discovery. +5. Check routing and access-control policy. +6. Review logs with synchronized timestamps. +7. Make the smallest reversible change and verify recovery. + +## Official references + +- [Cisco IOS and NX-OS software documentation](https://www.cisco.com/c/en/us/support/ios-nx-os-software/index.html) +- [Cisco IOS XE configuration guides](https://www.cisco.com/c/en/us/support/ios-nx-os-software/ios-xe/index.html) \ No newline at end of file From ab6ddef82091c377694aafd77c32a17243050f1d Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:20:30 -0500 Subject: [PATCH 11/27] Correct and modernize Arista EOS reference --- arista.md | 376 +++++++++++++++++++++++++++--------------------------- 1 file changed, 186 insertions(+), 190 deletions(-) diff --git a/arista.md b/arista.md index 5ffeb0b..aca820f 100644 --- a/arista.md +++ b/arista.md @@ -1,190 +1,186 @@ -# Arista Command Cheat Sheet - -This cheat sheet compiles a range of commands specifically for network engineers working with Arista switches. It covers various aspects of network troubleshooting and configuration, including OSPF, Layer 2 issues, and general device management. - -Intended as a quick reference guide, this document aims to streamline the process of managing Arista network environments and to assist in efficient problem-solving. Remember to apply these commands judiciously, as they can have a substantial impact on network performance and stability. - - -## BGP (Border Gateway Protocol) Management - -- **show ip bgp** - - Shows the BGP routing table. - -- **show ip bgp summary** - - Provides a summary of BGP neighbor relationships. - -- **show ip bgp neighbors** - - Displays detailed information about BGP neighbors. - -- **router bgp [AS_NUMBER]** - - Configures BGP with a specific Autonomous System (AS) number. - -- **neighbor [IP_ADDRESS] remote-as [AS_NUMBER]** - - Configures a BGP neighbor. - -- **network [IP_ADDRESS] mask [NETMASK]** - - Advertises a network in BGP. - -- **show ip bgp neighbors [IP_ADDRESS] advertised-routes** - - Displays the routes advertised to a specific BGP neighbor. - -- **show ip bgp neighbors [IP_ADDRESS] received-routes** - - Shows routes received from a specific BGP neighbor. - -- **show ip bgp regexp [REGEXP]** - - Displays routes matching a specific regular expression in BGP. - -- **clear ip bgp [IP_ADDRESS]** - - Clears a specific BGP session. - -- **show ip bgp community [COMMUNITY]** - - Displays routes with a specific BGP community tag. - -- **show ip bgp dampening parameters** - - Displays the BGP route dampening parameters. - -- **show ip bgp filter-list [LIST_NUMBER]** - - Shows routes that match a specific BGP filter list. - -- **show ip bgp flap-statistics** - - Displays BGP flap statistics. - -- **show ip bgp paths** - - Shows path information for BGP routes. - -- **show ip bgp policy** - - Displays the BGP policy information. - -- **show ip bgp route-map [MAP_NAME]** - - Shows routes that match a specific route-map in BGP. - -- **show ip bgp summary longer-prefixes** - - Displays a summary of BGP with longer prefixes. - -- **show ip bgp update-group** - - Shows BGP update group information. - -- **show running-config bgp** - - Displays the current BGP configuration. - -## VRRP (Virtual Router Redundancy Protocol) - -- **show vrrp** - - Displays VRRP configurations and status. - -- **show running-config vrrp** - - Displays the running configuration specific to VRRP. - -- **vrrp [GROUP_ID] ip [IP_ADDRESS]** - - Configures a VRRP group with an IP address. - -- **vrrp [GROUP_ID] priority [PRIORITY_LEVEL]** - - Sets the priority for a VRRP group. - -- **vrrp [GROUP_ID] preempt** - - Enables preemption in a VRRP group. - -- **show vrrp brief** - - Provides a brief overview of VRRP status. - -- **show vrrp detail** - - Displays detailed VRRP information. - -## VLAN and Interface Configuration - -- **show interfaces Vlan [VLAN_ID]** - - Shows configuration and status of a specific VLAN interface. - -- **vlan [VLAN_ID]** - - Creates a VLAN or enters VLAN configuration mode. - -- **interface Vlan [VLAN_ID]** - - Enters configuration mode for a specific VLAN interface. - -- **show vlan** - - Displays VLAN information and status. - -- **show interfaces trunk** - - Shows trunk interface status and configurations. - -- **spanning-tree vlan [VLAN_ID] priority [PRIORITY]** - - Sets the spanning-tree priority for a VLAN. - -- **show spanning-tree detail** - - Displays detailed spanning-tree information. - -## OSPF (Open Shortest Path First) - -- **show ip ospf neighbor** - - Displays OSPF neighbor relationships and states. - -- **show ip ospf interface** - - Shows OSPF-related information on interfaces. - -- **show ip ospf database** - - Displays the OSPF link-state database (LSDB). - -- **show ip route ospf** - - Shows routes learned via OSPF. - -- **show ip ospf traffic** - - Displays OSPF traffic statistics. - -- **show ip ospf border-routers** - - Shows OSPF border routers in the network. - -- **show ip ospf virtual-links** - - Displays OSPF virtual link configurations. - -- **debug ip ospf events** - - Enables OSPF event debugging for more granular troubleshooting. - -## General Network Management - -- **configure terminal** - - Enters global configuration mode. - -- **show ip route vrf [VRF_NAME]** - - Shows the IP routing table for a specific VRF. - -- **show vrf** - - Displays VRF configurations and status. - -- **ip route [DESTINATION] [MASK] [NEXT_HOP_IP]** - - Configures a static route. - -- **show ip interface brief** - - Summarizes the status and configuration of all IP interfaces. - -- **show interfaces description** - - Displays interface descriptions and status. - -- **show interfaces status** - - Shows the link status of all interfaces. - -- **show interfaces counters errors** - - Displays interface error counters. - -- **show interfaces counters rate** - - Shows the rate of traffic on interfaces. - -- **write memory** - - Saves the current configuration to the startup configuration file. - -- **show logging** - - Displays the system log for potential error messages or alerts. - -- **show mlag detail** - - Provides detailed information on MLAG status. - -- **show mac address-table** - - Shows the MAC address table. - -- **show etherchannel summary** - - Provides a summary of EtherChannel status. - -- **show ip arp** - - Shows the ARP table, useful for resolving IP to MAC address mappings. - -- **show lldp neighbors** - - Displays LLDP neighbor information, useful for verifying network topology. +# Arista EOS Cheat Sheet + +> **Applies to:** Common Arista EOS data-center switching workflows +> **Last reviewed:** 2026-07-14 + +Command availability varies by EOS release and hardware platform. This sheet uses Arista terminology such as port-channel and MLAG rather than Cisco EtherChannel commands. + +## Safety + +> [!WARNING] +> Clearing routing sessions, changing MLAG peer links, modifying trunks, or enabling debug output can interrupt production traffic. Capture state and validate a rollback plan first. + +## System state + +```text +show version +show inventory +show hostname +show running-config +show startup-config +show logging last 100 +show clock +show processes top once +show environment all +show reload cause +show extensions +``` + +## Interfaces + +```text +show interfaces status +show interfaces description +show ip interface brief +show interfaces +show interfaces counters errors +show interfaces counters errors +show interfaces counters rates +show running-config interfaces +show transceiver detail +``` + +## VLANs and trunks + +```text +show vlan +show vlan +show interfaces trunk +show interfaces switchport +show spanning-tree +show spanning-tree vlan +show spanning-tree inconsistentports +``` + +Example access port: + +```text +interface + description + switchport mode access + switchport access vlan + spanning-tree portfast +``` + +Example trunk: + +```text +interface + description + switchport mode trunk + switchport trunk allowed vlan +``` + +## Port-channels and LACP + +```text +show port-channel summary +show port-channel dense +show lacp neighbor +show lacp counters all-ports +show interfaces Port-Channel +``` + +Example LACP member: + +```text +interface + channel-group mode active +``` + +## MLAG + +```text +show mlag +show mlag detail +show mlag interfaces +show mlag config-sanity +show mlag issu warnings +show interfaces Port-Channel +show interfaces Vlan +``` + +Check these before changing MLAG: + +- peer-link state and member consistency; +- peer-address reachability; +- reload-delay and dual-primary settings; +- VLAN consistency across peers; +- orphaned ports and single-homed dependencies. + +## BGP + +```text +show ip bgp summary +show bgp ipv4 unicast summary +show ip bgp neighbors +show ip bgp +show ip bgp neighbors advertised-routes +show ip bgp neighbors received-routes +show ip route bgp +show running-config section router bgp +``` + +Prefer a soft inbound or outbound refresh when policy permits rather than resetting the TCP session: + +```text +clear ip bgp soft in +clear ip bgp soft out +``` + +## OSPF + +```text +show ip ospf +show ip ospf neighbor +show ip ospf interface +show ip ospf database +show ip route ospf +``` + +## Routing, VRFs, MAC, and ARP + +```text +show ip route +show ip route +show vrf +show ip route vrf +show mac address-table +show mac address-table interface +show ip arp +show ip arp vrf +show lldp neighbors detail +``` + +## Configuration sessions and rollback + +Use a configuration session for changes that benefit from an explicit diff: + +```text +configure session +show session-config diffs +commit +``` + +Save a validated running configuration: + +```text +copy running-config startup-config +``` + +Confirm the exact session and rollback behavior for the deployed EOS release before relying on it during remote maintenance. + +## Troubleshooting workflow + +1. Verify system health and timestamps. +2. Check interface state, optics, errors, and rates. +3. Validate VLAN, trunk, spanning-tree, and port-channel consistency. +4. For dual-homed services, check MLAG state and config sanity. +5. Confirm MAC, ARP, VRF, and route resolution. +6. Inspect routing-protocol neighbors and policy. +7. Make the smallest reversible change and verify both peers afterward. + +## Official references + +- [Arista EOS documentation](https://www.arista.com/en/support/product-documentation) +- [Arista EOS Central](https://www.arista.com/en/support/toi/eos) \ No newline at end of file From 154a8866c8e3fe11450bee6fd12d32bf0ea6f98d Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:20:55 -0500 Subject: [PATCH 12/27] Correct iptables guidance and add nftables context --- iptables.md | 292 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 190 insertions(+), 102 deletions(-) diff --git a/iptables.md b/iptables.md index 2cab34f..460971e 100644 --- a/iptables.md +++ b/iptables.md @@ -1,102 +1,190 @@ -# iptables Command Cheat Sheet - -This document provides a comprehensive list of iptables commands, crucial for network administrators and security professionals. iptables is the default firewall tool on Linux systems, used for network packet filtering and manipulation. - -The cheat sheet covers basic to advanced iptables functionalities, including setting up firewalls, NAT, port forwarding, and managing traffic rules. It serves as a handy guide for securing Linux systems and managing network traffic flows. Given the powerful nature of iptables, it is advised to use these commands with caution, as incorrect usage can lead to network outages or security vulnerabilities. - ---- - -1. **List All Rules** - - `sudo iptables -L` - - Lists all active rules. -2. **List Rules with Numbers** - - `sudo iptables -L --line-numbers` - - Lists rules with line numbers for easier management. -3. **Delete Rule by Number** - - `sudo iptables -D INPUT [LINE_NUMBER]` - - Deletes a specific rule from the INPUT chain. -4. **Set Default Policy** - - `sudo iptables -P [CHAIN] [POLICY]` - - Sets the default policy (e.g., ACCEPT, DROP) for a chain (e.g., INPUT, OUTPUT). -5. **Allow Specific Port (TCP)** - - `sudo iptables -A INPUT -p tcp --dport [PORT] -j ACCEPT` - - Allows incoming traffic on a specific TCP port. -6. **Allow Specific Port (UDP)** - - `sudo iptables -A INPUT -p udp --dport [PORT] -j ACCEPT` - - Allows incoming traffic on a specific UDP port. -7. **Drop Traffic from an IP Address** - - `sudo iptables -A INPUT -s [IP_ADDRESS] -j DROP` - - Blocks all incoming traffic from a specific IP address. -8. **Allow Traffic from an IP Address** - - `sudo iptables -A INPUT -s [IP_ADDRESS] -j ACCEPT` - - Allows all incoming traffic from a specific IP address. -9. **Reject Traffic on a Port** - - `sudo iptables -A INPUT -p tcp --dport [PORT] -j REJECT` - - Rejects traffic on a specific port. -10. **Save iptables Rules** - - `sudo iptables-save > /etc/iptables/rules.v4` - - Saves the current rules to a file (Debian-based systems). -11. **Flush All Rules** - - `sudo iptables -F` - - Removes all rules. - ---- - -1. **Log Dropped Packets** - - `sudo iptables -A INPUT -j LOG --log-prefix "IPTables-Dropped: " --log-level 4` - - Logs dropped packets for debugging. -2. **Limit Connections per Second** - - `sudo iptables -A INPUT -p tcp --dport [PORT] -m limit --limit [RATE] -j ACCEPT` - - Limits the number of connections per second to a port. -3. **Port Forwarding** - - `sudo iptables -t nat -A PREROUTING -p tcp --dport [PORT] -j DNAT --to-destination [DEST_IP]:[DEST_PORT]` - - Forwards traffic from one port to another IP and port. -4. **Masquerade (NAT)** - - `sudo iptables -t nat -A POSTROUTING -o [OUT_INTERFACE] -j MASQUERADE` - - Enables NAT for outgoing traffic on an interface. -5. **Drop Invalid Packets** - - `sudo iptables -A INPUT -m state --state INVALID -j DROP` - - Drops packets that are invalid. -6. **Allow Established and Related Connections** - - `sudo iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT` - - Allows incoming traffic related to established connections. -7. **Block Outgoing Traffic to a Domain** - - `sudo iptables -A OUTPUT -p tcp -d [DOMAIN] --dport 80 -j DROP` - - Blocks outgoing HTTP traffic to a specific domain. -8. **Redirect Traffic to Another Port** - - `sudo iptables -t nat -A PREROUTING -p tcp --dport [PORT] -j REDIRECT --to-port [NEW_PORT]` - - Redirects traffic from one port to another port on the same machine. -9. **Block Ping Requests** - - `sudo iptables -A INPUT -p icmp --icmp-type echo-request -j DROP` - - Blocks ICMP echo requests (ping). -10. **Allow Traffic on Multiple Ports** - - `sudo iptables -A INPUT -p tcp -m multiport --dports [PORT1],[PORT2],[PORT3] -j ACCEPT` - - Allows traffic on multiple specified ports. -11. **Rate Limiting Incoming Connections** - - `sudo iptables -A INPUT -p tcp --dport [PORT] -m state --state NEW -m recent --set` - - `sudo iptables -A INPUT -p tcp --dport [PORT] -m state --state NEW -m recent --update --seconds [SECONDS] --hitcount [HITCOUNT] -j DROP` - - Limits new connections to a port within a given timeframe. -12. **Block Traffic from a Specific Network** - - `sudo iptables -A INPUT -s [NETWORK/MASK] -j DROP` - - Blocks all incoming traffic from a specific network. -13. **Allow Traffic Only from a Specific Network** - - `sudo iptables -A INPUT -s [NETWORK/MASK] -j ACCEPT` - - Allows traffic only from a specific network. -14. **Log New Connections** - - `sudo iptables -A INPUT -m state --state NEW -j LOG --log-prefix "New Connection: "` - - Logs new incoming connections. -15. **Drop Outgoing Traffic to a Specific Port** - - `sudo iptables -A OUTPUT -p tcp --dport [PORT] -j DROP` - - Blocks outgoing traffic to a specific port. -16. **Redirect All HTTP Traffic to HTTPS** - - `sudo iptables -t nat -A PREROUTING -p tcp --dport 80 -j REDIRECT --to-port 443` - - Redirects all HTTP traffic to HTTPS. -17. **Block Outgoing SMTP Mail** - - `sudo iptables -A OUTPUT -p tcp --dport 25 -j REJECT` - - Blocks outgoing SMTP mail. -18. **Allow SSH Access from a Specific Network** - - `sudo iptables -A INPUT -p tcp --dport 22 -s [NETWORK/MASK] -j ACCEPT` - - Allows SSH access only from a specific network. -19. **Block Outgoing Telnet** - - `sudo iptables -A OUTPUT -p tcp --dport 23 -j DROP` - - Blocks outgoing Telnet connections. +# iptables Cheat Sheet + +> **Applies to:** Linux systems using the iptables command interface +> **Last reviewed:** 2026-07-14 + +`iptables` is still widely used, but many current Linux distributions use the nftables framework underneath or prefer the native `nft` command. Confirm whether the host uses `iptables-legacy`, `iptables-nft`, firewalld, UFW, or native nftables before changing rules. + +## Safety + +> [!DANGER] +> A remote firewall change can immediately lock you out. Keep an existing privileged session open, save the current rules, schedule an automatic rollback when possible, and verify console or out-of-band access. + +## Identify the firewall backend + +```bash +iptables --version +update-alternatives --display iptables 2>/dev/null || true +nft list ruleset +systemctl status firewalld --no-pager +ufw status verbose +``` + +## Back up and inspect + +```bash +sudo iptables-save > "iptables-backup-$(date +%Y%m%d-%H%M%S).rules" +sudo iptables -S +sudo iptables -L --numeric --verbose --line-numbers +sudo iptables -t nat -S +sudo iptables -t mangle -S +``` + +Use `-C` to check whether a rule already exists: + +```bash +sudo iptables -C INPUT -p tcp --dport -j ACCEPT +``` + +## Common stateful rules + +Prefer `conntrack` rather than the older `state` match: + +```bash +sudo iptables -A INPUT -m conntrack --ctstate INVALID -j DROP +sudo iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT +sudo iptables -A INPUT -i lo -j ACCEPT +``` + +Allow SSH from a management network: + +```bash +sudo iptables -A INPUT \ + -p tcp \ + -s \ + --dport 22 \ + -m conntrack --ctstate NEW \ + -j ACCEPT +``` + +Allow a TCP or UDP service: + +```bash +sudo iptables -A INPUT -p tcp --dport -j ACCEPT +sudo iptables -A INPUT -p udp --dport -j ACCEPT +``` + +## Rule order + +Rules are evaluated in order. Insert a rule at a specific position when required: + +```bash +sudo iptables -I INPUT +``` + +Delete by exact rule specification when possible: + +```bash +sudo iptables -D INPUT -p tcp --dport -j ACCEPT +``` + +Or review numbered rules and then delete a line: + +```bash +sudo iptables -L INPUT --numeric --line-numbers +sudo iptables -D INPUT +``` + +Line numbers change after deletion, so list the chain again before deleting another rule. + +## Default policies + +Inspect current policies before changing them: + +```bash +sudo iptables -S +``` + +Example policy change: + +```bash +sudo iptables -P INPUT DROP +sudo iptables -P FORWARD DROP +sudo iptables -P OUTPUT ACCEPT +``` + +> [!WARNING] +> Add required management, loopback, established-session, and service rules **before** setting a default DROP policy. + +## Logging with rate limiting + +```bash +sudo iptables -A INPUT \ + -m limit --limit 5/min --limit-burst 10 \ + -j LOG --log-prefix "iptables-input-drop: " --log-level warning +``` + +An unconditional LOG rule can flood system logs. + +## NAT and forwarding + +Enable IPv4 forwarding using persistent system configuration rather than a one-off command: + +```bash +sysctl net.ipv4.ip_forward +``` + +Masquerade traffic leaving an interface: + +```bash +sudo iptables -t nat -A POSTROUTING -o -j MASQUERADE +``` + +Destination NAT: + +```bash +sudo iptables -t nat -A PREROUTING \ + -i \ + -p tcp --dport \ + -j DNAT --to-destination : +``` + +Also permit the forwarded traffic in the `FORWARD` chain and validate the return path. + +## Rate limiting + +```bash +sudo iptables -A INPUT \ + -p tcp --dport \ + -m conntrack --ctstate NEW \ + -m limit --limit /second --limit-burst \ + -j ACCEPT +``` + +## Misleading patterns to avoid + +- An iptables destination using a DNS name is resolved when the rule is created; it does not continuously track DNS changes. +- Redirecting TCP port 80 to 443 does not add TLS. The application on the destination port must actually speak TLS. +- Dropping all ICMP can break Path MTU Discovery and troubleshooting. Filter specific types only with a documented reason. +- Flushing rules remotely without a tested rollback can disconnect the host. + +## Persistence + +Persistence is distribution-specific. On Debian-based systems using `iptables-persistent`: + +```bash +sudo iptables-save | sudo tee /etc/iptables/rules.v4 >/dev/null +sudo ip6tables-save | sudo tee /etc/iptables/rules.v6 >/dev/null +``` + +Verify the persistence service and restore behavior before rebooting. + +## Restore and rollback + +Validate a saved ruleset in a lab when possible, then restore: + +```bash +sudo iptables-restore < iptables-backup.rules +``` + +For remote maintenance, use `iptables-apply` when available because it can automatically roll back unconfirmed changes: + +```bash +sudo iptables-apply +``` + +## Official references + +- [Netfilter documentation](https://www.netfilter.org/documentation/) +- [iptables manual](https://man7.org/linux/man-pages/man8/iptables.8.html) +- [nftables wiki](https://wiki.nftables.org/) \ No newline at end of file From 52dacfcbec2d5d19bd3db4042c82676fdf52490e Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:21:29 -0500 Subject: [PATCH 13/27] Modernize Azure service names and CLI examples --- azure.md | 289 ++----------------------------------------------------- 1 file changed, 7 insertions(+), 282 deletions(-) diff --git a/azure.md b/azure.md index b16618f..a408274 100644 --- a/azure.md +++ b/azure.md @@ -1,285 +1,10 @@ -# Azure Cheat Sheet +# Microsoft Azure and Azure CLI Cheat Sheet -## Overview +> **Applies to:** Current Azure CLI 2.x and common Azure resource-management workflows +> **Last reviewed:** 2026-07-14 -Microsoft Azure is a comprehensive cloud platform offering a wide array of services for computing, storage, networking, and more. This cheat sheet provides a concise reference to essential Azure services and commands. +## Current terminology ---- - -# Azure Fundamentals (AZ-900) Cheat Sheet - -## 1. Cloud Concepts - -- **Cloud Computing:** Understand the basics of cloud computing, including its benefits such as scalability, reliability, and cost-efficiency. -- **Cloud Models:** - - *Public Cloud:* Services offered over the public internet. - - *Private Cloud:* Dedicated services for a single organization. - - *Hybrid Cloud:* Combination of public and private clouds. -- **Cloud Service Types:** - - *Infrastructure as a Service (IaaS):* Provides virtualized computing resources. - - *Platform as a Service (PaaS):* Offers hardware and software tools over the internet. - - *Software as a Service (SaaS):* Delivers software applications over the internet. - -## 2. Core Azure Services - -- **Compute Services:** - - *Azure Virtual Machines:* Deploy and manage virtual machines. - - *Azure App Service:* Host web apps and RESTful APIs. - - *Azure Kubernetes Service (AKS):* Manage Kubernetes clusters. - - *Azure Container Instances (ACI):* Run containers without managing servers. - - *Azure Functions:* Serverless compute for event-driven workloads. -- **Storage Services:** - - *Azure Blob Storage:* Object storage solution for unstructured data. - - *Azure Disk Storage:* High-performance disk storage for VMs. - - *Azure File Storage:* Managed file shares accessible via SMB/NFS. - - *Azure Queue Storage:* Messaging between application components. -- **Networking Services:** - - *Azure Virtual Network (VNet):* Establish private networks in the cloud. - - *Azure Load Balancer:* Distribute incoming network traffic. - - *Azure Application Gateway:* Application-level routing and load balancing. - - *Azure VPN Gateway:* Site-to-site and point-to-site VPN connectivity. - - *Azure ExpressRoute:* Dedicated private connectivity to Azure. -- **Database Services:** - - *Azure SQL Database:* Managed relational database service. - - *Azure Cosmos DB:* Globally distributed, multi-model database. - - *Azure Database for MySQL/PostgreSQL:* Managed open-source database services. - -## 3. Security, Privacy, Compliance, and Trust - -- **Azure Active Directory (AD):** Cloud-based identity and access management service. -- **Role-Based Access Control (RBAC):** Manage user access to Azure resources. -- **Azure Security Center / Microsoft Defender for Cloud:** Unified security management system. -- **Azure Key Vault:** Manage and safeguard cryptographic keys and secrets. -- **Azure DDoS Protection:** Protect against distributed denial-of-service attacks. -- **Microsoft Sentinel:** Cloud-native SIEM and SOAR solution. - -## 4. Azure Pricing and Support - -- **Pricing Models:** - - *Consumption-Based:* Pay-as-you-go based on actual usage. - - *Reserved Instances:* Commit to 1 or 3 years for discounted rates. - - *Spot Instances:* Use unused Azure capacity at deep discounts. -- **Total Cost of Ownership (TCO) Calculator:** Estimate cost savings by migrating to Azure. -- **Azure Pricing Calculator:** Estimate costs for specific Azure configurations. -- **Service Level Agreements (SLAs):** Understand uptime guarantees for Azure services. -- **Support Plans:** - - *Basic:* Free support for billing and subscription issues. - - *Developer:* For trial and non-production environments. - - *Standard:* For production workloads. - - *Professional Direct:* For business-critical dependence. - - *Premier:* Enterprise-level proactive support. - -## 5. Azure Management Tools - -- **Azure Portal:** Web-based interface for managing Azure services. -- **Azure CLI:** Command-line tool for managing Azure resources. -- **Azure PowerShell:** PowerShell module for Azure management. -- **Azure Resource Manager (ARM):** Deployment and management service for Azure. -- **Azure Bicep:** Domain-specific language for deploying Azure resources (simpler than ARM JSON). -- **Azure Cloud Shell:** Browser-based shell with Azure CLI and PowerShell pre-installed. - ---- - -## Azure Command-Line Interface (CLI) - -Azure CLI is a command-line tool for managing Azure resources. Below are common commands: - -### Login and Account Management - -```bash -# Login interactively -az login - -# Login with a service principal -az login --service-principal -u [APP_ID] -p [PASSWORD] --tenant [TENANT_ID] - -# List subscriptions -az account list --output table - -# Set active subscription -az account set --subscription [SUBSCRIPTION_ID] - -# Show current account -az account show -``` - -### Resource Groups - -```bash -# Create a Resource Group -az group create --name MyResourceGroup --location eastus - -# List Resource Groups -az group list --output table - -# Show a specific Resource Group -az group show --name MyResourceGroup - -# Delete a Resource Group -az group delete --name MyResourceGroup --yes --no-wait -``` - -### Virtual Machines - -```bash -# Create a VM -az vm create \ - --resource-group MyResourceGroup \ - --name MyVM \ - --image UbuntuLTS \ - --admin-username azureuser \ - --generate-ssh-keys - -# List VMs -az vm list --output table - -# Start a VM -az vm start --resource-group MyResourceGroup --name MyVM - -# Stop (deallocate) a VM -az vm stop --resource-group MyResourceGroup --name MyVM - -# Restart a VM -az vm restart --resource-group MyResourceGroup --name MyVM - -# Delete a VM -az vm delete --resource-group MyResourceGroup --name MyVM --yes - -# Get VM details -az vm show --resource-group MyResourceGroup --name MyVM - -# List VM sizes in a region -az vm list-sizes --location eastus --output table - -# Open a port on a VM -az vm open-port --resource-group MyResourceGroup --name MyVM --port 80 -``` - -### Storage Accounts - -```bash -# Create a Storage Account -az storage account create \ - --name mystorageaccount \ - --resource-group MyResourceGroup \ - --location eastus \ - --sku Standard_LRS - -# List Storage Accounts -az storage account list --resource-group MyResourceGroup --output table - -# Show Storage Account keys -az storage account keys list --account-name mystorageaccount --resource-group MyResourceGroup - -# Delete a Storage Account -az storage account delete --name mystorageaccount --resource-group MyResourceGroup --yes - -# Upload a file to Blob Storage -az storage blob upload \ - --account-name mystorageaccount \ - --container-name mycontainer \ - --name myblob \ - --file ./localfile.txt - -# List blobs in a container -az storage blob list --account-name mystorageaccount --container-name mycontainer --output table -``` - -### Azure Kubernetes Service (AKS) - -```bash -# Create an AKS Cluster -az aks create \ - --resource-group MyResourceGroup \ - --name MyAKSCluster \ - --node-count 2 \ - --enable-addons monitoring \ - --generate-ssh-keys - -# List AKS Clusters -az aks list --output table - -# Get AKS Credentials (configure kubectl) -az aks get-credentials --resource-group MyResourceGroup --name MyAKSCluster - -# Scale AKS Cluster node count -az aks scale --resource-group MyResourceGroup --name MyAKSCluster --node-count 3 - -# Upgrade AKS Cluster -az aks upgrade --resource-group MyResourceGroup --name MyAKSCluster --kubernetes-version [VERSION] - -# Show AKS Cluster details -az aks show --resource-group MyResourceGroup --name MyAKSCluster --output table - -# Stop AKS Cluster (save costs when not in use) -az aks stop --resource-group MyResourceGroup --name MyAKSCluster - -# Start AKS Cluster -az aks start --resource-group MyResourceGroup --name MyAKSCluster - -# Delete AKS Cluster -az aks delete --resource-group MyResourceGroup --name MyAKSCluster --yes -``` - -### Networking - -```bash -# Create a Virtual Network -az network vnet create \ - --resource-group MyResourceGroup \ - --name MyVNet \ - --address-prefix 10.0.0.0/16 - -# Create a Subnet -az network vnet subnet create \ - --resource-group MyResourceGroup \ - --vnet-name MyVNet \ - --name MySubnet \ - --address-prefixes 10.0.1.0/24 - -# Create a Network Security Group -az network nsg create --resource-group MyResourceGroup --name MyNSG - -# Add an NSG rule -az network nsg rule create \ - --resource-group MyResourceGroup \ - --nsg-name MyNSG \ - --name AllowSSH \ - --protocol tcp \ - --priority 1000 \ - --destination-port-range 22 \ - --access Allow - -# Create a Public IP -az network public-ip create --resource-group MyResourceGroup --name MyPublicIP - -# List VNets -az network vnet list --output table -``` - -### Azure Active Directory / Entra ID - -```bash -# List users -az ad user list --output table - -# Create a user -az ad user create --display-name "John Doe" --password [PASSWORD] --user-principal-name john@example.com - -# List service principals -az ad sp list --output table - -# Create a service principal -az ad sp create-for-rbac --name MyServicePrincipal --role Contributor --scopes /subscriptions/[SUBSCRIPTION_ID] - -# List role assignments -az role assignment list --output table -``` - -### Tips for Using Azure CLI - -- **Output Formatting**: Use `--output` (`-o`) with `json`, `jsonc`, `table`, `tsv`, or `yaml` for different output formats. -- **Queries**: Use `--query` with JMESPath syntax to filter output: `az vm list --query "[].{Name:name, Location:location}" --output table` -- **Help**: Use `az [command] --help` for detailed documentation on any command. -- **Version Update**: Keep Azure CLI updated: `az upgrade` -- **Interactive Mode**: Use `az interactive` for an auto-complete shell experience. +- **Microsoft Entra ID** is the current name for Azure Active Directory. +- **Microsoft Defender for Cloud** is the current name for Azure Security Center. +- Azure Resource Manager (ARM) is the control plane used by the portal, CLI, \ No newline at end of file From 23ef0fb578ef21e4eb2b18de93e3f20308985c5b Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:22:01 -0500 Subject: [PATCH 14/27] Modernize Google Cloud CLI reference --- gcloud.md | 242 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 141 insertions(+), 101 deletions(-) diff --git a/gcloud.md b/gcloud.md index 11fbf85..bf5de66 100644 --- a/gcloud.md +++ b/gcloud.md @@ -1,101 +1,141 @@ -### GCP `gcloud` CLI Cheat Sheet - -#### Introduction to GCP `gcloud` CLI -The `gcloud` command-line interface is a part of the Google Cloud SDK and provides a way to manage GCP services and resources. - -- **Purpose**: Manage GCP resources, automate tasks, and handle administrative tasks. - ---- - -#### Initial Setup and Configuration -**Install Google Cloud SDK** -- Installation varies by operating system and is available on the GCP documentation site. - -**Initialize gcloud CLI** -- `gcloud init` -- Initializes the gcloud environment, sets up the default configuration, project, and authenticates user. - -**Set Default Project** -- `gcloud config set project [PROJECT_ID]` -- Sets a default project for gcloud commands. - -#### Managing Compute Engine -**List Compute Instances** -- `gcloud compute instances list` -- Lists all Compute Engine instances in the current project. - -**Create Compute Instance** -- `gcloud compute instances create [INSTANCE_NAME] --zone [ZONE]` -- Creates a new Compute Engine instance in the specified zone. - -**Stop Compute Instance** -- `gcloud compute instances stop [INSTANCE_NAME] --zone [ZONE]` -- Stops a running Compute Engine instance. - -**Delete Compute Instance** -- `gcloud compute instances delete [INSTANCE_NAME] --zone [ZONE]` -- Deletes a specified Compute Engine instance. - -#### Working with Kubernetes Engine -**List Kubernetes Clusters** -- `gcloud container clusters list` -- Lists all Kubernetes clusters in the current project. - -**Create Kubernetes Cluster** -- `gcloud container clusters create [CLUSTER_NAME] --zone [ZONE]` -- Creates a new Kubernetes cluster in the specified zone. - -**Get Kubernetes Cluster Credentials** -- `gcloud container clusters get-credentials [CLUSTER_NAME] --zone [ZONE]` -- Fetches credentials for interacting with the Kubernetes cluster. - -**Delete Kubernetes Cluster** -- `gcloud container clusters delete [CLUSTER_NAME] --zone [ZONE]` -- Deletes a specified Kubernetes cluster. - -#### Managing Cloud Storage -**List Storage Buckets** -- `gsutil ls` -- Lists all Cloud Storage buckets in the current project. - -**Create Storage Bucket** -- `gsutil mb gs://[BUCKET_NAME]` -- Creates a new Cloud Storage bucket. - -**Copy Files to/from Storage Bucket** -- `gsutil cp [LOCAL_FILE] gs://[BUCKET_NAME]/[OBJECT_NAME]` -- `gsutil cp gs://[BUCKET_NAME]/[OBJECT_NAME] [LOCAL_FILE]` -- Copies files to or from a Cloud Storage bucket. - -#### Managing IAM and Service Accounts -**List IAM Roles** -- `gcloud iam roles list` -- Lists all available IAM roles in the current project. - -**Create Service Account** -- `gcloud iam service-accounts create [ACCOUNT_NAME]` -- Creates a new service account. - -**Assign IAM Role to Service Account** -- `gcloud projects add-iam-policy-binding [PROJECT_ID] --member "serviceAccount:[ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com" --role "[ROLE]"` -- Assigns an IAM role to a service account. - -#### Networking and VPC -**List VPC Networks** -- `gcloud compute networks list` -- Lists all VPC networks in the current project. - -**Create VPC Network** -- `gcloud compute networks create [NETWORK_NAME] --subnet-mode=custom` -- Creates a new VPC network with custom subnet mode. - -**Create Firewall Rule** -- `gcloud compute firewall-rules create [RULE_NAME] --network [NETWORK_NAME] --allow [PROTOCOL]:[PORT]` -- Creates a firewall rule in the specified VPC network. - ---- - -#### Tips for Using GCP `gcloud` CLI -- **Regular Updates**: Keep the Google Cloud SDK updated for the latest features and security updates. -- **Useful Flags**: Explore flags like `--format` to customize output and `--help` for command usage. -- **Scripting**: Integrate `gcloud` commands into scripts for automation and efficient cloud management. +# Google Cloud CLI Cheat Sheet + +> **Applies to:** Current Google Cloud CLI (`gcloud`) +> **Last reviewed:** 2026-07-14 + +A practical reference for authentication, configuration, Compute Engine, GKE, Cloud Storage, IAM, and networking. + +## Authentication and configuration + +```bash +gcloud version +gcloud init +gcloud auth login +gcloud auth list +gcloud config configurations list +gcloud config list +gcloud config set project +gcloud config set compute/region +gcloud config set compute/zone +gcloud projects list +``` + +For local Application Default Credentials used by client libraries: + +```bash +gcloud auth application-default login +``` + +> [!WARNING] +> Do not confuse user CLI credentials with Application Default Credentials. Use workload identity or service-account impersonation for automation instead of downloading long-lived keys whenever possible. + +## Service-account impersonation + +```bash +gcloud auth print-access-token \ + --impersonate-service-account= + +gcloud config set auth/impersonate_service_account +gcloud config unset auth/impersonate_service_account +``` + +## Compute Engine + +```bash +gcloud compute instances list +gcloud compute instances describe --zone= +gcloud compute instances create \ + --zone= \ + --machine-type= \ + --image-family=debian-12 \ + --image-project=debian-cloud +gcloud compute ssh --zone= +gcloud compute instances stop --zone= +gcloud compute instances start --zone= +gcloud compute instances delete --zone= +``` + +## Google Kubernetes Engine + +```bash +gcloud container clusters list +gcloud container clusters describe --location= +gcloud container clusters get-credentials \ + --location= +gcloud container clusters create \ + --location= \ + --num-nodes=3 +gcloud container clusters resize \ + --location= \ + --num-nodes= +gcloud container clusters delete \ + --location= +``` + +## Cloud Storage + +Use the current `gcloud storage` command group for new scripts: + +```bash +gcloud storage buckets list +gcloud storage buckets create gs:// --location= +gcloud storage ls gs:// +gcloud storage cp gs:/// +gcloud storage cp gs:/// +gcloud storage rsync --recursive gs:/// +gcloud storage rm gs:/// +``` + +`gsutil` remains available in many installations, but do not introduce it into new automation unless compatibility requires it. + +## IAM and service accounts + +```bash +gcloud iam roles list +gcloud iam service-accounts list +gcloud iam service-accounts create \ + --display-name="" +gcloud projects get-iam-policy +gcloud projects add-iam-policy-binding \ + --member="serviceAccount:" \ + --role="roles/" +``` + +Avoid project-owner and broad primitive roles. Prefer predefined or custom roles with the minimum required permissions. + +## VPC networking + +```bash +gcloud compute networks list +gcloud compute networks describe +gcloud compute networks create --subnet-mode=custom +gcloud compute networks subnets list +gcloud compute networks subnets create \ + --network= \ + --region= \ + --range= +gcloud compute firewall-rules list +gcloud compute firewall-rules create \ + --network= \ + --direction=INGRESS \ + --action=ALLOW \ + --rules=tcp: \ + --source-ranges= +``` + +## Output and troubleshooting + +```bash +gcloud --help +gcloud info +gcloud topic formats +gcloud compute instances list \ + --format='table(name,zone.basename(),status,networkInterfaces[0].networkIP)' +gcloud components update +``` + +## References + +- [Google Cloud CLI documentation](https://cloud.google.com/sdk/gcloud) +- [Cloud Storage with the gcloud CLI](https://cloud.google.com/storage/docs/discover-object-storage-gcloud) +- [Service-account impersonation](https://cloud.google.com/docs/authentication/use-service-account-impersonation) From f5fb5c052fa39a8053208fe7f5a970533bd4d3a8 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:22:20 -0500 Subject: [PATCH 15/27] Replace misspelled Kubernetes reference --- kubernetes.md | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 150 insertions(+) create mode 100644 kubernetes.md diff --git a/kubernetes.md b/kubernetes.md new file mode 100644 index 0000000..bf3b17c --- /dev/null +++ b/kubernetes.md @@ -0,0 +1,150 @@ +# Kubernetes and kubectl Cheat Sheet + +> **Applies to:** Current supported Kubernetes releases +> **Last reviewed:** 2026-07-14 + +A quick reference for cluster context, workloads, logs, rollouts, node maintenance, and troubleshooting. + +## Context and namespaces + +```bash +kubectl version --client +kubectl cluster-info +kubectl config current-context +kubectl config get-contexts +kubectl config use-context +kubectl config set-context --current --namespace= +kubectl get namespaces +``` + +## Discover resources + +```bash +kubectl api-resources +kubectl api-versions +kubectl explain deployment +kubectl explain deployment.spec.template.spec.containers +``` + +## List and inspect + +```bash +kubectl get nodes -o wide +kubectl get pods -A -o wide +kubectl get deployments,statefulsets,daemonsets -A +kubectl get services,ingresses -A +kubectl get events -A --sort-by=.metadata.creationTimestamp +kubectl describe pod -n +kubectl get pod -n -o yaml +``` + +## Apply and diff + +```bash +kubectl diff -f +kubectl apply -f +kubectl delete -f +kubectl apply --server-side -f +``` + +Prefer declarative manifests over imperative production changes. Run `kubectl diff` before applying when possible. + +## Logs and process access + +```bash +kubectl logs -n +kubectl logs -n -c +kubectl logs -n --previous +kubectl logs -f -n --since=10m +kubectl exec -it -n -- /bin/sh +kubectl cp /:/remote/path ./local-path +``` + +## Rollouts and scaling + +```bash +kubectl rollout status deployment/ -n +kubectl rollout history deployment/ -n +kubectl rollout undo deployment/ -n +kubectl scale deployment/ -n --replicas= +kubectl set image deployment/ \ + =: \ + -n +``` + +## Port forwarding and temporary diagnostics + +```bash +kubectl port-forward service/ 8080: -n +kubectl port-forward pod/ 8080: -n +kubectl run net-debug \ + --rm -it \ + --restart=Never \ + --image=nicolaka/netshoot \ + -- /bin/bash +kubectl debug node/ -it --image=ubuntu +``` + +Use only trusted diagnostic images approved by your organization. + +## Resource usage + +```bash +kubectl top nodes +kubectl top pods -A +kubectl top pod -n --containers +``` + +The Metrics API must be available for `kubectl top`. + +## Node maintenance + +```bash +kubectl cordon +kubectl drain \ + --ignore-daemonsets \ + --delete-emptydir-data +kubectl uncordon +``` + +> [!WARNING] +> `drain` evicts workloads and `--delete-emptydir-data` discards ephemeral data. Check PodDisruptionBudgets, local storage, singleton workloads, and replacement capacity first. + +## Labels, annotations, and taints + +```bash +kubectl label node = +kubectl label node - +kubectl annotate / = -n +kubectl taint node =:NoSchedule +kubectl taint node :NoSchedule- +``` + +## JSONPath and custom columns + +```bash +kubectl get pods -A \ + -o custom-columns='NS:.metadata.namespace,NAME:.metadata.name,NODE:.spec.nodeName,PHASE:.status.phase' + +kubectl get nodes \ + -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.nodeInfo.kubeletVersion}{"\n"}{end}' +``` + +## Common troubleshooting sequence + +```bash +kubectl get pod -n -o wide +kubectl describe pod -n +kubectl logs -n --all-containers --previous +kubectl get events -n --sort-by=.metadata.creationTimestamp +kubectl get endpoints,endpointslices -n +kubectl get networkpolicies -n +``` + +Check scheduling events, image pulls, probes, resource limits, service selectors, endpoint population, DNS, and network policy before restarting workloads blindly. + +## References + +- [kubectl reference](https://kubernetes.io/docs/reference/kubectl/) +- [Debug applications](https://kubernetes.io/docs/tasks/debug/debug-application/) +- [Safely drain a node](https://kubernetes.io/docs/tasks/administer-cluster/safely-drain-node/) From c0586c4b6db707bb384c8666b7c536d0a7bd676d Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:22:28 -0500 Subject: [PATCH 16/27] Remove misspelled Kubernetes file --- kubernates.md | 99 --------------------------------------------------- 1 file changed, 99 deletions(-) delete mode 100644 kubernates.md diff --git a/kubernates.md b/kubernates.md deleted file mode 100644 index eb89123..0000000 --- a/kubernates.md +++ /dev/null @@ -1,99 +0,0 @@ -# Kubernetes Command Cheat Sheet - -This cheat sheet is a comprehensive guide to Kubernetes commands, designed for DevOps engineers, system administrators, and anyone working with Kubernetes. Kubernetes is a powerful container orchestration system that automates the deployment, scaling, and management of containerized applications. - -The commands are categorized into sections for easy reference, covering everything from basic interactions to more advanced management and troubleshooting. This guide aims to streamline Kubernetes operations and provide quick access to common commands necessary for effective cluster management and deployment troubleshooting. - -## Basic Interactions -- **kubectl get nodes** - - Lists all nodes in the cluster. - -- **kubectl get pods** - - Lists all pods in the current namespace. - -- **kubectl get pods -n [namespace]** - - Lists all pods in a specific namespace. - -- **kubectl get services** - - Lists all services in the current namespace. - -- **kubectl get deployments** - - Lists all deployments in the current namespace. - -- **kubectl describe node [node_name]** - - Shows detailed information about a node. - -- **kubectl describe pod [pod_name]** - - Shows detailed information about a pod. - -## Resource Management -- **kubectl create -f [file.yaml]** - - Creates a resource from a YAML file. - -- **kubectl apply -f [file.yaml]** - - Applies changes to a resource from a YAML file. - -- **kubectl delete -f [file.yaml]** - - Deletes a resource defined in a YAML file. - -- **kubectl scale deployment [deployment_name] --replicas=[num]** - - Scales a deployment to a specific number of replicas. - -- **kubectl rollout status deployment/[deployment_name]** - - Checks the rollout status of a deployment. - -- **kubectl set image deployment/[deployment_name] [container_name]=[image:tag]** - - Updates the image of a deployment. - -- **kubectl exec -it [pod_name] -- [command]** - - Executes a command in a running pod. - -- **kubectl logs [pod_name]** - - Fetches logs from a pod. - -- **kubectl port-forward [pod_name] [local_port]:[pod_port]** - - Forwards a local port to a port on the pod. - -## Cluster Administration -- **kubectl cluster-info** - - Displays cluster info. - -- **kubectl top node** - - Shows metrics for nodes. - -- **kubectl top pod** - - Shows metrics for pods. - -- **kubectl cordon [node_name]** - - Marks a node as unschedulable. - -- **kubectl drain [node_name]** - - Drains a node in preparation for maintenance. - -- **kubectl uncordon [node_name]** - - Marks a node as schedulable. - -- **kubectl taint nodes [node_name] key=value:effect** - - Applies a taint to a node. - -- **kubectl edit [resource] [name]** - - Edits a resource in the default editor. - -## Networking and Debugging -- **kubectl run [pod_name] --image=[image]** - - Runs a temporary pod with a specific image. - -- **kubectl attach [pod_name] -i** - - Attaches to a running container. - -- **kubectl expose deployment [deployment_name] --type=[type] --port=[port]** - - Exposes a deployment as a new Kubernetes service. - -- **kubectl get events** - - Lists cluster events, useful for debugging. - -- **kubectl get namespaces** - - Lists all namespaces in the cluster. - -- **kubectl config view** - - Shows the Kubernetes configuration. From bf13e4923ed35c2ff5ef71f6f2e29fdd4e8ddb29 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:22:32 -0500 Subject: [PATCH 17/27] Remove employer-specific interview dossier --- quic-masque-srv6.md | 1385 ------------------------------------------- 1 file changed, 1385 deletions(-) delete mode 100644 quic-masque-srv6.md diff --git a/quic-masque-srv6.md b/quic-masque-srv6.md deleted file mode 100644 index ef3133f..0000000 --- a/quic-masque-srv6.md +++ /dev/null @@ -1,1385 +0,0 @@ -# QUIC, MASQUE & SRv6 — Datum Cloud Interview Cheat Sheet -### Network Engineering Reference — Focused on Datum's Open Network Cloud Architecture - ---- - -## Table of Contents - -1. [Datum Cloud — Architecture Overview](#datum-cloud--architecture-overview) - - [What is Datum?](#what-is-datum) - - [Founding Team & Lineage](#founding-team--lineage) - - [The Three Pillars: Edge, Tunnels, Backbone](#the-three-pillars) - - [Open Source Stack](#open-source-stack) - - [Control Plane Architecture](#control-plane-architecture) - - [Infrastructure Layout](#infrastructure-layout) -2. [QUIC](#quic) - - [What is QUIC?](#what-is-quic) - - [Why QUIC Exists — The Problems It Solves](#why-quic-exists) - - [Protocol Stack Comparison](#protocol-stack-comparison) - - [QUIC Internals](#quic-internals) - - [Packet Structure](#quic-packet-structure) - - [Connection Establishment](#quic-connection-establishment) - - [Key Features In Depth](#quic-key-features-in-depth) - - [QUIC & HTTP/3](#quic--http3) - - [Iroh — How Datum Uses QUIC](#iroh--how-datum-uses-quic) - - [Impact on Network Infrastructure](#impact-on-network-infrastructure) -3. [MASQUE](#masque) - - [What is MASQUE?](#what-is-masque) - - [Protocol Stack](#masque-protocol-stack) - - [How MASQUE Works](#how-masque-works) - - [MASQUE Mechanisms](#masque-mechanisms) - - [Packet Structure & Encapsulation](#masque-packet-structure--encapsulation) - - [Real-World Use Cases](#masque-real-world-use-cases) - - [Relevance to Datum's Architecture](#masque-relevance-to-datum) -4. [SRv6](#srv6) - - [What is SRv6?](#what-is-srv6) - - [SRv6 vs MPLS — Why the Shift?](#srv6-vs-mpls) - - [Core Concepts](#srv6-core-concepts) - - [SRv6 Packet Structure](#srv6-packet-structure) - - [SRH — Segment Routing Header](#srh--segment-routing-header) - - [SRv6 Network Programming — Endpoint Behaviors](#srv6-network-programming) - - [Micro-SID (uSID) — Compressed SRv6](#usid--compressed-srv6) - - [SRv6 Encapsulation Modes](#srv6-encapsulation-modes) - - [Control Plane](#srv6-control-plane) - - [SRv6 TE — Traffic Engineering](#srv6-te--traffic-engineering) - - [SRv6 for VPN Services](#srv6-for-vpn-services) - - [How Datum Uses SRv6](#how-datum-uses-srv6) - - [Real-World Deployment Use Cases](#srv6-real-world-deployment-use-cases) -5. [Datum's Full-Stack Architecture — How Everything Connects](#datums-full-stack-architecture) - - [End-to-End Traffic Flow at Datum](#end-to-end-traffic-flow) - - [The Operational Tension: SRv6 + QUIC Encryption](#operational-tension) - - [Envoy — The Edge Proxy](#envoy--the-edge-proxy) - - [HickoryDNS](#hickorydns) - - [Crossplane — Cloud Provider Normalization](#crossplane) - - [Galactic VPCs](#galactic-vpcs) -6. [Interview Talking Points — Key Concepts to Demonstrate](#interview-talking-points) -7. [Key RFCs & References](#key-rfcs--references) - ---- - -# Datum Cloud — Architecture Overview - -## What is Datum? - -Datum is an **open-source network cloud** — a neutral platform where alt clouds, tech incumbents, and digital leaders can programmatically interact with their unique ecosystem. Datum provides the networking "superpowers" that large companies like hyperscalers and CDNs have (global edges, private networks, deterministic routing, direct interconnection) and makes them available to every developer, startup, and AI agent. - -The core thesis: the internet is becoming fragmented (the "Splinternet") as regulations, sovereignty requirements, and the explosion of alt-cloud providers make the flat, open internet model obsolete. At the same time, AI agents and modern applications deploy everywhere — not just `us-east-1`. Datum provides the private networking layer that these applications need without requiring a dedicated network team. - -> **One-liner**: Datum is what you'd build if you wanted to give every AI agent and alt-cloud provider the same networking capabilities that Cloudflare, AWS, and Equinix have — global edge, encrypted tunnels, deterministic backbone routing — as a self-service, open-source platform. - ---- - -## Founding Team & Lineage - -Datum was founded by industry veterans from **Voxel, Packet, Equinix, Fastly, and StackPath**. The CEO, Zac Smith, co-founded Packet (bare-metal cloud automation, acquired by Equinix for $335M in 2020) and previously ran Equinix Metal. The team has deep experience in bare-metal infrastructure, peering/interconnection, edge computing, and SP-grade networking. - -This lineage matters for understanding Datum's architecture — these are people who deeply understand: -- Physical internet infrastructure (data centers, IXPs, cross-connects) -- Peering and transit economics -- SP-grade network programmability (which is why SRv6 is central to the backbone) -- Developer-first API design (the Packet philosophy) - -The company is licensed under **AGPLv3** for core components. - ---- - -## The Three Pillars - -Datum's product architecture has three foundational networking layers: - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ │ -│ ┌──────────────────────┐ ┌──────────────────────┐ ┌──────────────┐ │ -│ │ 1. EDGE │ │ 2. TUNNELS │ │ 3. BACKBONE │ │ -│ │ │ │ │ │ │ │ -│ │ Envoy-based proxy │ │ QUIC P2P tunnels │ │ SRv6 overlay│ │ -│ │ + Coraza WAF │ │ built with Iroh │ │ "fast lanes"│ │ -│ │ + AI Gateway │ │ + NAT traversal │ │ + VPC-style │ │ -│ │ │ │ + zero trust certs │ │ control │ │ -│ │ 17+ global PoPs │ │ + hole punching │ │ + telemetry │ │ -│ └──────────────────────┘ └──────────────────────┘ └──────────────┘ │ -│ │ -│ Kubernetes-native Control Plane │ -│ (CRDs + Crossplane + Controllers) │ -│ │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -### Pillar 1: Edge -An intelligent **Envoy proxy** layer that protects and routes global internet traffic to backend services. Includes a WAF (Coraza, open-source), bot/DDoS protection, and the **Envoy AI Gateway** for routing traffic from application clients to Generative AI services. Deployed across 17+ global points of presence. - -### Pillar 2: Tunnels (Connectors) -**Peer-to-peer QUIC tunnels** built on **Iroh** (a Rust library from n0.computer). Zero trust, certificate-based routing. The primary use case today is safely exposing localhost/internal services to the internet. Iroh handles: -- NAT traversal via UDP hole punching -- Relay server fallback (when direct P2P fails) -- End-to-end encryption (relay cannot inspect payload) -- Connection migration across network changes - -### Pillar 3: Backbone -**SRv6 overlay** providing deterministic, auditable internet "fast lanes." This is the private backbone — controllable routing paths with VPC-style control and real-time observability (OpenTelemetry metrics export to Grafana Cloud). Unlike traditional private networks that take years to build, Datum aims to make virtual backbones available in minutes. - ---- - -## Open Source Stack - -Datum leans heavily into open-source projects. Key components: - -| Component | Role in Datum | Technology | -|---|---|---| -| **Datum** (core) | System for managing/connecting network and data workloads | AGPLv3, Kubernetes-native | -| **Iroh** | P2P QUIC connectivity, NAT traversal, tunnels | Rust, fork of Quinn (QUIC impl) | -| **Envoy** | Edge proxy, service mesh, traffic routing | C++, CNCF graduated | -| **Envoy AI Gateway** | Routes traffic to GenAI services | Extension of Envoy Gateway | -| **Crossplane** | Control plane framework, normalizes cloud provider integrations | Kubernetes CRDs | -| **HickoryDNS** | Authoritative DNS service across 17 locations | Rust, safe/secure DNS | -| **SRv6** | Backbone deterministic routing via Segment Routing Header | IPv6 extension headers | -| **Milo** | "Business OS" for product-led B2B companies | Internal tooling | -| **Coraza WAF** | Web Application Firewall at the edge | Open source, OWASP compatible | - ---- - -## Control Plane Architecture - -Datum's control plane is built on **Kubernetes Custom Resource Definitions (CRDs)**. This is a deliberate architectural choice: - -**Why Kubernetes as the control plane?** -- Extensibility: CRDs for simple schema-backed types, API Aggregation for custom server behavior -- Built-in authn/authz (OIDC, RBAC, Webhooks) with policy in the API -- Audit logs out of the box -- Reconciliation loops (controllers) — infrastructure self-heals to desired state -- Ecosystem familiarity: kubectl, watches, admission webhooks, OpenAPI discovery -- LLM compatibility: Claude, GPT, etc. have deep familiarity with the Kubernetes codebase - -**How it works:** -``` -User (datumctl / kubectl / Datum MCP for Cursor / API) - │ - ▼ -Kubernetes API Server (CRDs define Datum resources) - │ - ├── Organizations → Projects (hierarchy with inherited policy) - ├── Network resources (VPCs, tunnels, routes, DNS) - ├── Edge resources (HTTPProxy, WAF rules) - ├── Compute resources - │ - ▼ -Crossplane Controllers - │ - ├── Reconcile desired state → actual state - ├── Normalize across cloud providers (AWS, Azure, GCP, bare metal) - └── Continuous reconciliation (drift detection, auto-repair) -``` - -This approach follows **KEP-4080** (Kubernetes Enhancement Proposal) — factoring out the generic parts of kube-apiserver and kube-controller-manager into reusable libraries for building control planes that don't need container orchestration semantics. - -The tooling includes: -- **datumctl**: CLI with K8s-style syntax (get, apply, delete) -- **Datum MCP**: Official Model Context Protocol server for Cursor integration -- **Developer Tools**: macOS, Windows, Linux desktop apps - ---- - -## Infrastructure Layout - -Datum deploys infrastructure in **top internet aggregation points globally** using a region/AZ model: - -| Field | Description | Example | -|---|---|---| -| Geography | ISO country code | US, DE, IN | -| Cardinal Direction | north, south, east, west, central | west | -| Number | Region index | 1 | -| Count | Availability Zone | a, b, c | - -Example: `us-west-1a` - -Each Region = geographic and network boundary. Each AZ = independent capacity within that Region. Currently 17+ global PoPs. - ---- - -# QUIC - -## What is QUIC? - -QUIC is a general-purpose, encrypted transport protocol standardized by the IETF in **RFC 9000 (May 2021)**. It runs over **UDP** and is designed to replace TCP+TLS for latency-sensitive, high-performance applications. - -Originally developed by Google (~2012) as an internal protocol for Chrome and Google services, it was adopted and standardized by the IETF with significant changes. The IETF version of QUIC is distinct from Google's original "gQUIC." - -> **One-liner**: QUIC is what you get when you take TCP + TLS 1.3 + HTTP/2 multiplexing, throw out 40 years of TCP legacy, and rebuild it cleanly over UDP with encryption mandatory from the ground up. - -> **Datum context**: QUIC is the transport foundation for Datum's tunnel/connector layer via Iroh — every P2P connection between Datum endpoints is a QUIC connection, not TCP. - ---- - -## Why QUIC Exists - -### The Problems QUIC Solves - -**1. TCP Head-of-Line (HoL) Blocking** -- HTTP/2 multiplexes many streams over a single TCP connection -- If one TCP segment is lost, **all streams stall** waiting for retransmission — even streams with no missing data -- TCP sees one byte stream; it has no concept of independent application streams - -``` -TCP + HTTP/2 HoL Blocking: - -Stream A: [chunk1] [chunk2] [ LOST ] [chunk4] ← all streams wait here -Stream B: [chunk1] [chunk2] STALLED STALLED -Stream C: [chunk1] STALLED STALLED -``` - -**2. TCP Handshake Latency** -- TCP 3-way handshake = 1 RTT before any data flows -- TLS 1.3 adds another 1 RTT on top (2 RTT total for first connection) -- TLS 1.3 resumed sessions: still 1 RTT (TCP) + 0 RTT (TLS) = 1 RTT - -**3. Ossification** -- Middleboxes (firewalls, NATs, LBs, DPI) have learned to read and manipulate TCP headers -- TCP protocol cannot evolve because middleboxes break on unknown options -- QUIC solves this by **encrypting nearly everything** — middleboxes see only UDP + QUIC Connection ID - -**4. Connection Migration** -- TCP connections = {src IP, src port, dst IP, dst port} 4-tuple -- Network change (Wi-Fi → LTE) = source IP changes → TCP breaks → reconnect needed -- QUIC uses **Connection IDs** — seamless migration across network changes -- **Datum relevance**: This is critical for Iroh — P2P tunnels survive network transitions without reconnecting - -**5. No Kernel Involvement for Protocol Evolution** -- TCP lives in the OS kernel; changes require OS upgrades -- QUIC runs in userspace — updates ship as fast as application updates - ---- - -## Protocol Stack Comparison - -``` -Traditional HTTPS HTTP/2 HTTP/3 (QUIC) -───────────────── ────────────── ───────────────────────── - -┌─────────────┐ ┌───────────┐ ┌─────────────────────────┐ -│ HTTP/1.1 │ │ HTTP/2 │ │ HTTP/3 │ -├─────────────┤ ├───────────┤ ├─────────────────────────┤ -│ TLS 1.2 │ │ TLS 1.3 │ │ QUIC │ -├─────────────┤ ├───────────┤ │ (streams + crypto + │ -│ TCP │ │ TCP │ │ flow control + CC) │ -├─────────────┤ ├───────────┤ ├─────────────────────────┤ -│ IP │ │ IP │ │ UDP │ -└─────────────┘ └───────────┘ ├─────────────────────────┤ - │ IP │ - └─────────────────────────┘ - -RTT to first byte: RTT to first byte: RTT to first byte: -New: 2 RTT New: 2 RTT New: 1 RTT -Resume: 1 RTT Resume: 1 RTT Resume: 0 RTT (0-RTT) -``` - ---- - -## QUIC Internals - -### Connection Lifecycle - -``` -Client Server - │ │ - │──── Initial (ClientHello) ────────>│ ← Crypto handshake starts immediately - │ │ in the first packet (no separate TCP SYN) - │<─── Initial (ServerHello) ─────────│ - │<─── Handshake (cert, finish) ──────│ - │ │ - │──── Handshake (finish) ───────────>│ ← 1 RTT: connection established + encrypted - │ │ - │<═══ Application Data ══════════════│ ← Data flows immediately after - │═══> Application Data ══════════════│ - │ │ - │ (0-RTT resumption on next conn) │ - │──── 0-RTT Data + ClientHello ─────>│ ← 0 RTT: data sent before server responds -``` - -### QUIC Packet Number Spaces - -QUIC uses three separate packet number spaces, each with its own encryption level: - -| Space | Encryption | Purpose | -|---|---|---| -| Initial | AEAD with fixed key (from spec) | Bootstrap crypto — Client/Server Hello | -| Handshake | AEAD with handshake keys | Certificate, Finished messages | -| Application (1-RTT) | AEAD with session keys | All application data + most QUIC frames | - -Packet loss in one space doesn't affect others — each space has independent ACK and retransmission. - -### Streams - -QUIC multiplexes independent, ordered byte streams over a single connection: - -- Each stream is independently flow-controlled -- Loss in Stream A does **not** block Stream B (no HoL blocking) -- Stream types: - - **Bidirectional** (client-initiated: 0, 4, 8... / server-initiated: 1, 5, 9...) - - **Unidirectional** (client-initiated: 2, 6, 10... / server-initiated: 3, 7, 11...) -- Stream IDs are 62-bit variable-length integers - -``` -Single QUIC Connection — Multiple Independent Streams: - - ┌──────────────────────────────────┐ - │ QUIC Connection │ - │ Connection ID: 0xA3F2... │ - │ │ - │ Stream 0 ────────────────────> │ (request 1) - │ Stream 4 ──────────> │ (request 2) - │ Stream 8 ──────────────────> │ (request 3) - │ Stream 1 <──────────────────── │ (server push) - │ │ - │ Each stream: independent ACK, │ - │ flow control, retransmission │ - └──────────────────────────────────┘ -``` - -### Congestion Control - -- QUIC does not mandate a specific CC algorithm -- Default: **NewReno** or **CUBIC** (same as TCP) -- Userspace implementation means **BBR** can be deployed without OS changes — important for high-BDP paths -- QUIC packet numbering eliminates retransmission ambiguity (RFC 9002) - -### Connection Migration - -``` -Mobile Client Server - │ │ - │ [on Wi-Fi, src: 192.168.1.5:4321] │ - │═══════════════════════════════════> │ CID: 0xDEADBEEF - │ │ - │ [switches to LTE, src: 10.0.0.1:9876] - │ │ - │══ PATH_CHALLENGE ════════════════> │ ← Client validates new path - │<═ PATH_RESPONSE ══════════════════ │ - │ │ - │═══════════════════════════════════> │ CID: 0xDEADBEEF (unchanged) - │ [LTE, same Connection ID] │ ← No reconnect. No re-handshake. -``` - ---- - -## QUIC Packet Structure - -### Long Header Packet (handshake) - -``` - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤ -│1│ Type │ Reserved │ PKT# Len │ Version (32 bits) │ -├─┴───────┴───────────┴───────────┼───────────────────────────────┤ -│ DCID Len (8) │ Dest Conn ID (0-20 bytes) │ -├────────────────┼───────────────────────────────────────────────┤ -│ SCID Len (8) │ Source Conn ID (0-20 bytes) │ -├────────────────┴───────────────────────────────────────────────┤ -│ Type-specific fields (Token, Length, Packet Number) │ -├────────────────────────────────────────────────────────────────┤ -│ Payload (AEAD-encrypted frames) │ -└────────────────────────────────────────────────────────────────┘ - -Header bit 1 = 1 → Long Header (handshake/version negotiation) -Types: Initial (0x00), 0-RTT (0x01), Handshake (0x02), Retry (0x03) -``` - -### Short Header Packet (application data — 1-RTT) - -``` - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -├─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┼─┤ -│0│1│S│R│R│K│ PKT# │ Dest Connection ID (variable, 0-20 bytes) │ -├─┴─┴─┴─┴─┴─┴──────┴────────────────────────────────────────────┤ -│ Packet Number (1-4 bytes) │ -├────────────────────────────────────────────────────────────────┤ -│ Payload (AEAD-encrypted QUIC frames) │ -└────────────────────────────────────────────────────────────────┘ - -S = Spin bit (for passive RTT measurement by network devices) -K = Key phase bit (tracks key rotation) -Header bit 0 = 0 → Short Header (1-RTT application data) - -What a middlebox can see: UDP src/dst port, Connection ID, Spin bit -Everything else is encrypted — including stream IDs, frame types, payload -``` - -### Key QUIC Frame Types (inside encrypted payload) - -| Frame Type | Purpose | -|---|---| -| STREAM | Carries application stream data | -| ACK | Acknowledges received packets | -| CRYPTO | Carries TLS handshake data | -| CONNECTION_CLOSE | Terminates connection | -| MAX_DATA | Flow control — connection level | -| MAX_STREAM_DATA | Flow control — stream level | -| NEW_CONNECTION_ID | Provides new CIDs (for migration) | -| PATH_CHALLENGE / PATH_RESPONSE | Validates new network path | -| PING | Keeps connection alive | -| HANDSHAKE_DONE | Signals handshake completion (server→client) | -| DATAGRAM (RFC 9221) | Unreliable datagrams within a QUIC connection | - ---- - -## QUIC Connection Establishment - -### First Connection (1 RTT) - -``` -t=0 Client sends Initial packet: - - CRYPTO frame carrying TLS ClientHello - - src/dst CIDs chosen by client - - Token (empty on first connection) - -t=0.5 RTT Server responds: - - Initial: CRYPTO (ServerHello) - - Handshake: CRYPTO (EncryptedExtensions, Certificate, CertVerify, Finished) - - Can also send 1-RTT data early - -t=1 RTT Client sends: - - Handshake: CRYPTO (Finished) — handshake complete - - 1-RTT: Application data begins flowing - -Total: 1 RTT to first application byte -``` - -### Resumed Connection (0-RTT) - -``` -t=0 Client sends: - - Initial: CRYPTO (ClientHello with session ticket) - - 0-RTT: Application data (sent immediately, before server responds) - ← Encrypted with keys from previous session - -t=0.5 RTT Server responds and can immediately handle 0-RTT data - -Total: 0 RTT — application data sent before server's first response - -Caveat: 0-RTT data is vulnerable to replay attacks. - Servers must handle 0-RTT data idempotently. - Non-idempotent requests (e.g., payments) should not use 0-RTT. -``` - ---- - -## QUIC Key Features In Depth - -### The Spin Bit — Passive RTT Measurement - -The spin bit (bit 2 of short header) toggles once per RTT, allowing passive RTT measurement without decryption: - -``` -Client →→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→ Server -spin=0 →→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→ - spin=1 ←←←←←←←←←←← -spin=1 →→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→→ - spin=0 ←←←←←←←←←←← - -Network tap measures time between transitions = 1 RTT -This is the ONLY latency signal available to middleboxes in QUIC. -``` - -**Datum relevance**: On the SRv6 backbone, the spin bit is one of the few observability signals available for QUIC flows — critical for the backbone's telemetry and performance monitoring. - -### Loss Recovery - -- TCP reuses sequence numbers for retransmissions → ambiguity about which transmission was ACKed -- QUIC uses **monotonically increasing packet numbers** — retransmitted data gets a new number -- Eliminates retransmission ambiguity, enables accurate RTT measurement during loss (RFC 9002) - -### QUIC Versions - -| Version | Status | Notes | -|---|---|---| -| Draft versions (< 29) | Obsolete | Google gQUIC, pre-standardization | -| QUIC v1 (0x00000001) | RFC 9000 — Current standard | What HTTP/3 and Iroh use | -| QUIC v2 (0x6b3343cf) | RFC 9369 | Minor improvements, greasing version ossification | - ---- - -## QUIC & HTTP/3 - -HTTP/3 is HTTP semantics (methods, headers, status codes) carried over QUIC instead of TCP. - -``` -HTTP/3 internal structure over QUIC: - -QUIC Stream 0 (bidi, client-init): HTTP/3 request/response -QUIC Stream 4 (bidi, client-init): Another HTTP/3 request/response -QUIC Stream 2 (uni, client-init): QPACK encoder stream -QUIC Stream 6 (uni, client-init): HTTP/3 control stream -QUIC Stream 3 (uni, server-init): QPACK decoder stream -QUIC Stream 7 (uni, server-init): HTTP/3 control stream (server) -``` - -**QPACK** replaces HTTP/2's HPACK for header compression. Designed for out-of-order delivery on QUIC streams (HPACK required ordered processing, which was itself a HoL blocking risk). - ---- - -## Iroh — How Datum Uses QUIC - -This is the section most directly relevant to Datum's architecture. Iroh is not HTTP/3 — it's a **connectivity library** that uses QUIC as a raw transport for building P2P protocols. - -### What is Iroh? - -Iroh is a Rust library built by **n0.computer** that establishes direct peer-to-peer QUIC connections. It uses a fork of **Quinn**, a pure-Rust QUIC implementation. Datum uses Iroh for its "Connectors" / tunnel layer. - -### How Iroh P2P Connectivity Works - -``` -Endpoint A Relay Server Endpoint B -(NodeId: Ed25519 pubkey) (HTTP/1.1 over TLS) (NodeId: Ed25519 pubkey) - │ │ │ - │── Register (HTTP) ──────────>│<────── Register (HTTP) ──────│ - │ │ │ - │ [Phase 1: Relay fallback — works immediately] │ - │══ UDP datagram ══════════════│══ forward to B ══════════════>│ - │ (encrypted to B's NodeId) │ (relay cannot read payload) │ - │ │ │ - │ [Phase 2: Hole punching attempt — runs in background] │ - │ │ │ - │══ simultaneous UDP ══════════════════════════════════════> │ - │<════════════════════════════════════════ simultaneous UDP ═══│ - │ │ │ - │ [If hole punch succeeds: direct P2P QUIC connection] │ - │<════════════════════════════════════════════════════════════>│ - │ [Relay drops out, connection is now direct] │ -``` - -### Key Iroh/QUIC Design Decisions - -| Property | Detail | -|---|---| -| **Identity** | Ed25519 NodeId (cryptographic, not IP-based) | -| **NAT traversal** | UDP hole punching via relay coordination | -| **Fallback** | Relay server forwards encrypted UDP datagrams | -| **Relay security** | Payload always encrypted to destination — relay is blind | -| **Relay protocol** | HTTP/1.1 over TLS (most universally supported protocol) | -| **QUIC implementation** | Quinn (pure Rust), forked and maintained by n0.computer | -| **Multipath** | Active work on QUIC-MULTIPATH IETF draft in Quinn fork | -| **Stream API** | Exposes full QUIC stream semantics (bidi, uni, finish, reset, stop) | - -### Why QUIC for P2P (Not Just HTTP/3) - -Iroh deliberately exposes QUIC's stream API rather than abstracting it away because: -- QUIC is more expressive than TCP — multiple concurrent streams, fine-grained flow control, cancellation -- Protocol design matters — file transfer needs different patterns than chat or real-time collaboration -- Bidirectional streams can be stopped/reset as a unit -- Stream IDs are monotonically increasing — can determine ordering without application-level sequencing - -### Iroh vs Traditional VPN / Tunnel Approaches - -| | Traditional VPN | Iroh / Datum Tunnels | -|---|---|---| -| Architecture | Client-server, centralized gateway | P2P, decentralized | -| Identity | IP-based or certificate to gateway | Ed25519 cryptographic identity | -| NAT traversal | Requires gateway with public IP | Hole punching + relay fallback | -| Encryption overhead | IPsec/WireGuard encapsulation | QUIC TLS 1.3, native | -| Connection migration | Reconnect on network change | QUIC CID — seamless | -| Multiplexing | Single tunnel for all traffic | Multiple independent QUIC streams | -| Transport | TCP/UDP encapsulation | Native QUIC over UDP | -| Trust model | Trust the VPN server | Zero trust — relay cannot inspect | - ---- - -## Impact on Network Infrastructure - -### What Changes for Network Engineers - -**Firewall / ACL considerations:** -- QUIC runs on **UDP 443** by default. Firewalls that rate-limit or block UDP 443 will break QUIC -- QUIC uses ephemeral UDP ports — existing UDP tracking rules may need tuning - -**DPI / Traffic classification:** -- QUIC encrypts almost everything. Connection IDs are the only stable identifier -- SNI in Initial packet's CRYPTO frame is **not** encrypted in QUIC v1 (same as TLS 1.3). ECH will change this -- Flow classification tools need QUIC-specific parsers - -**Load balancer design:** -- 4-tuple routing breaks with connection migration -- QUIC-aware LBs use **Server Connection IDs** encoding routing info (RFC 9484 — QUIC-LB) -- Consistent hashing on Connection ID required - -**NAT behavior:** -- UDP NAT bindings time out faster than TCP (typically 30s vs 300s) -- QUIC uses **PING frames** to keep NAT bindings alive -- NAT timeout mismatches are a common operational issue - -**Monitoring:** -- Spin bit = your RTT signal -- Loss rate inferred from packet number gaps -- Flow-level telemetry (IPFIX/NetFlow) rather than payload inspection - ---- - -# MASQUE - -## What is MASQUE? - -**MASQUE** (Multiplexed Application Substrate over QUIC Encryption) is an IETF framework (RFC 9297, RFC 9298, RFC 9484) for building proxying and tunneling services on top of **HTTP/3 and QUIC**. - -It provides a standardized, encrypted mechanism for: -- **IP tunneling** (full Layer 3 proxy — like a VPN) -- **UDP proxying** (relay UDP datagrams — like TURN, but standardized) -- **TCP proxying** (CONNECT method, extended to QUIC) - -> **One-liner**: MASQUE is what you'd build if you needed to replace an MPLS VPN, GRE tunnel, or IPsec VPN with something that runs natively over HTTP/3, looks like regular HTTPS traffic, and supports multiplexing many tunnels over one QUIC connection. - -> **Datum context**: While Datum's current tunnel implementation uses Iroh (raw QUIC P2P), MASQUE represents the IETF-standardized approach to the same problem space. Understanding MASQUE provides context for the broader industry direction and potential future integration patterns. - ---- - -## MASQUE Protocol Stack - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Proxied Traffic │ -│ (IP packets, UDP datagrams, TCP streams) │ -├─────────────────────────────────────────────────────────────┤ -│ MASQUE Protocol │ -│ (Connect-IP / Connect-UDP / CONNECT / HTTP Datagrams) │ -├─────────────────────────────────────────────────────────────┤ -│ HTTP/3 │ -├─────────────────────────────────────────────────────────────┤ -│ QUIC │ -├─────────────────────────────────────────────────────────────┤ -│ UDP │ -├─────────────────────────────────────────────────────────────┤ -│ IP │ -└─────────────────────────────────────────────────────────────┘ -``` - ---- - -## How MASQUE Works - -MASQUE extends the HTTP **CONNECT** method to support UDP and IP: - -| Method | RFC | Tunnels | -|---|---|---| -| `CONNECT` (classic) | RFC 9110 | TCP streams | -| `CONNECT-UDP` | RFC 9298 | UDP datagrams | -| `CONNECT-IP` | RFC 9484 | IP packets (full L3 tunnel) | - -### Basic Flow - -``` -Client MASQUE Proxy Target - │ │ │ - │─── HTTP/3 CONNECT-UDP ────>│ │ - │ Target: 10.0.0.1:5004 │ │ - │ │ │ - │<─── 200 OK ────────────────│ (tunnel established) │ - │ │ │ - │═══ HTTP Datagram ══════════│══> UDP packet ════════════>│ - │ (UDP payload │ to 10.0.0.1:5004 │ - │ inside QUIC DATAGRAM) │ │ - │ │<══ UDP response ═══════════│ - │<══ HTTP Datagram ══════════│ │ - -All Client↔Proxy traffic: encrypted QUIC, looks like HTTPS (UDP 443) -``` - ---- - -## MASQUE Mechanisms - -### HTTP Datagrams (RFC 9297) - -Core data transport for MASQUE using QUIC **DATAGRAM** frames (RFC 9221): - -``` -QUIC DATAGRAM frame: -┌──────────────────────────────────────────────────────┐ -│ Quarter Stream ID (variable-length int) │ -├──────────────────────────────────────────────────────┤ -│ HTTP Datagram Payload │ -│ (e.g., UDP payload, IP packet) │ -└──────────────────────────────────────────────────────┘ - -Key: UNRELIABLE delivery (no retransmission) -→ Avoids double-retransmission for already-reliable traffic -``` - -### Capsule Protocol (Fallback) - -When QUIC DATAGRAM frames are unavailable (restrictive middleboxes), MASQUE falls back to the **Capsule Protocol** — datagrams inside HTTP/3 DATA frames on a reliable stream: - -``` -Trade-off: works through restrictive firewalls but adds HoL blocking -``` - -### CONNECT-IP — Full IP Tunneling (RFC 9484) - -``` -Client MASQUE Proxy Internet - │ │ │ - │ CONNECT-IP: "::/0" │ │ - │─────────────────────────────>│ │ - │<── 200 OK (assigns IP) ─────│ │ - │ │ │ - │══ IP packet (dst 8.8.8.8) ══>│═══ IP packet ════════════>│ - │ (inside HTTP Datagram) │ (NAT or route) │ - │ │<══ IP response ════════════│ - │<═ IP packet (src 8.8.8.8) ══│ │ - -Result: Client has a virtual IP, full internet access via proxy. - To observers: looks like HTTPS traffic to proxy IP. -``` - ---- - -## MASQUE Packet Structure & Encapsulation - -### Overhead Analysis - -| Component | Bytes | -|---|---| -| IPv6 outer header | 40 | -| UDP outer header | 8 | -| QUIC short header (min) | ~20 | -| QUIC DATAGRAM frame overhead | ~4 | -| Quarter Stream ID | 1–4 | -| **Total overhead (approx)** | **~75–80 bytes** | - -Comparison: IPsec ESP tunnel mode ≈ 50–70 bytes. MASQUE is slightly heavier but adds TLS 1.3 encryption + HTTP/3 multiplexing. - ---- - -## MASQUE Real-World Use Cases - -### iCloud Private Relay -Apple's two-hop MASQUE architecture: -- Hop 1: Apple ingress proxy (knows user identity, not destination) -- Hop 2: Third-party egress proxy (knows destination, not user identity) -- No single party knows both who the user is and where they're going - -### Zero Trust Network Access (ZTNA) -- Looks like normal HTTPS — passes through restrictive firewalls -- Per-application tunnels (not full VPN) — CONNECT-UDP per app -- QUIC multiplexing — many application tunnels over one connection - -### 5G ATSSS (Access Traffic Steering, Switching, Splitting) -- ATSSS proxy uses MASQUE CONNECT-UDP for multi-path traffic steering between Wi-Fi and cellular - ---- - -## MASQUE Relevance to Datum - -| Aspect | Datum's Approach | MASQUE Standard | -|---|---|---| -| Tunneling | Iroh (raw QUIC, P2P) | HTTP/3 extended CONNECT | -| Proxy model | Relay server (blind forward) | MASQUE proxy (protocol-aware) | -| NAT traversal | Hole punching + relay | CONNECT through HTTP proxy | -| Encryption | QUIC TLS 1.3 (Iroh) | QUIC TLS 1.3 (HTTP/3) | -| Multiplexing | QUIC streams | HTTP/3 + QUIC streams | - -While Datum currently uses Iroh rather than MASQUE, the concepts overlap significantly. MASQUE represents the IETF-standardized path for encrypted tunneling over HTTP/3, and future Datum features (like the "Galactic VPC" L3 connectivity) could draw on CONNECT-IP patterns. - ---- - -# SRv6 - -## What is SRv6? - -**SRv6** (Segment Routing over IPv6) is a source-based routing and network programming architecture where: -1. The **source node** encodes routing instructions (**segments**) directly into the IPv6 extension header -2. Intermediate nodes execute the instructions — **no per-flow state** in the network -3. Each segment is a **128-bit IPv6 address** encoding both a locator (where to route) and a function (what to do) - -Standardized by IETF Spring WG: RFC 8754 (SRH), RFC 8986 (SRv6 Network Programming). - -> **One-liner**: SRv6 is MPLS done with native IPv6 — no labels, no LDP, no RSVP-TE. The "label stack" is a list of IPv6 addresses in the packet header, and each hop executes a function based on its local SID definition. - -> **Datum context**: SRv6 is the underlay for Datum's backbone — the "fast lanes" that provide deterministic, auditable routing across Datum's global PoP infrastructure. This is not a 5G transport network; it's an open-source network cloud using SRv6 for **internet backbone programmability**. - ---- - -## SRv6 vs MPLS - -| Feature | MPLS | SRv6 | -|---|---|---| -| Data plane | 32-bit label stack | IPv6 extension header (SRH) | -| Control plane | LDP, RSVP-TE, BGP-LU | IS-IS, OSPF, BGP (with SID advertisements) | -| Per-flow state | Required for RSVP-TE tunnels | None (stateless forwarding) | -| Interoperability | Requires MPLS support end-to-end | Native IPv6 — any IPv6-capable device can transit | -| TE granularity | Tunnel-based | Per-packet source routing | -| VPN support | L3VPN (BGP VPNv4/v6) | BGP SRv6 L3VPN / EVPN | -| Overhead | 4 bytes per label | 16+ bytes per SID (larger, but no separate label plane) | -| Programmability | Limited | High — per-node function definition | -| OAM | MPLS OAM (RFC 8029) | Native IPv6 ping/traceroute works on SRv6 paths | - ---- - -## SRv6 Core Concepts - -### Segment Identifier (SID) - -An SRv6 SID is a **128-bit IPv6 address** structured as: - -``` -┌────────────────────────────┬───────────────┬─────────────┐ -│ Locator │ Function │ Args │ -│ (routable prefix) │ (what to do) │ (optional) │ -│ B bits │ F bits │ A bits │ -└────────────────────────────┴───────────────┴─────────────┘ - -Example: 2001:db8:1::/48 = Locator (node address prefix) - 0x0001 = Function (e.g., End.DT4 for IPv4 L3VPN) - :: = Args (empty) - -Full SID: 2001:db8:1::1 → End.DT4 function on node with locator 2001:db8:1::/48 -``` - -The locator is advertised into the IGP (IS-IS/OSPF) so other nodes know how to reach it. The function is locally significant. - -### Active Segment - -The **active segment** = current destination of the packet. The SRH contains a **Segments Left** counter indicating which SID to process next. - -### SRv6 Node Roles - -| Role | Description | -|---|---| -| **Ingress Node (SR Source)** | Adds the SRH with the segment list | -| **Transit Node** | Forwards based on outer IPv6 DA (no SRH processing if not a SID) | -| **Endpoint Node** | Processes the active SID — executes the defined function | -| **Egress Node** | Last segment endpoint — delivers to final destination | - ---- - -## SRv6 Packet Structure - -``` - Standard IPv6 Packet with SRH: - -┌─────────────────────────────────────────────────────────────┐ -│ IPv6 Base Header │ -│ Version=6, Traffic Class, Flow Label │ -│ Payload Length, Next Header=43 (Routing Header), Hop Limit │ -│ Source Address: Ingress Node │ -│ Destination Address: Current Active Segment (SID[n]) │ -├─────────────────────────────────────────────────────────────┤ -│ Segment Routing Header (SRH) │ -│ Next Header, Hdr Ext Len, Routing Type = 4 (SRv6) │ -│ Segments Left: n (countdown to 0) │ -│ Last Entry: index of last segment in list │ -│ Flags (8 bits), Tag (16 bits) │ -│ ┌───────────────────────────────────────────────────────┐ │ -│ │ Segment List[0]: SID of last segment (final dest) │ │ -│ │ Segment List[1]: SID of second-to-last segment │ │ -│ │ ... │ │ -│ │ Segment List[n]: SID of first segment (active now) │ │ -│ └───────────────────────────────────────────────────────┘ │ -│ Optional TLVs (Padding, HMAC, etc.) │ -├─────────────────────────────────────────────────────────────┤ -│ Inner Payload │ -│ (IPv4/IPv6 packet, Ethernet frame, etc.) │ -└─────────────────────────────────────────────────────────────┘ - -IMPORTANT: Segment list is ordered LAST to FIRST. - Segment List[n] = currently active SID (in IPv6 DA) - Segment List[0] = final destination SID - Segments Left decrements as each node processes its SID. -``` - -### SRH Processing at Each Hop - -``` -Ingress Node: - 1. Build SRH with segment list [SID_C, SID_B, SID_A] (last→first order) - 2. Set Segments Left = 2 - 3. Set IPv6 DA = SID_A (first segment = last in list) - 4. Forward packet - -At SID_A (Segments Left = 2): - 1. Execute function for SID_A - 2. Segments Left-- → 1 - 3. IPv6 DA = Segment List[1] = SID_B - 4. Forward packet - -At SID_B (Segments Left = 1): - 1. Execute function for SID_B - 2. Segments Left-- → 0 - 3. IPv6 DA = Segment List[0] = SID_C - 4. Forward packet - -At SID_C (Segments Left = 0): - 1. Execute function for SID_C (typically deliver payload) - 2. Remove SRH, deliver inner packet to destination -``` - ---- - -## SRH — Segment Routing Header - -``` - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -├─────────────────┬───────────────┬───────────────┬───────────────┤ -│ Next Header │ Hdr Ext Len │ Routing Type=4│ Segments Left │ -├─────────────────┴───────────────┴───────────────┴───────────────┤ -│ Last Entry │ Flags │ Tag │ -├─────────────────────────────────────────────────────────────────┤ -│ Segment List[0] (128 bits / 16 bytes) │ -│ (Final Destination SID) │ -├─────────────────────────────────────────────────────────────────┤ -│ ... │ -├─────────────────────────────────────────────────────────────────┤ -│ Segment List[n] (128 bits / 16 bytes) │ -│ (First/Active SID — also in IPv6 DA) │ -├─────────────────────────────────────────────────────────────────┤ -│ Optional TLVs │ -└─────────────────────────────────────────────────────────────────┘ - -Overhead per SID = 16 bytes -SRH fixed overhead = 8 bytes -Total overhead for n segments = 8 + (n × 16) bytes - -Example: 4-segment path = 8 + 64 = 72 bytes of SRH overhead -``` - ---- - -## SRv6 Network Programming - -SRv6 defines **endpoint behaviors** — standardized functions executed by nodes at the active segment (RFC 8986): - -| Behavior | Name | Description | -|---|---|---| -| `End` | Endpoint | Basic SID — update DA to next segment, forward | -| `End.X` | Endpoint with L3 cross-connect | Forward to specific L3 adjacency (TE use case) | -| `End.T` | Endpoint with Table lookup | Forward in specific routing table | -| `End.DX4` | Endpoint with decap + IPv4 cross-connect | Decap SRv6, forward IPv4 to specific NH (L3VPN egress) | -| `End.DX6` | Endpoint with decap + IPv6 cross-connect | Decap SRv6, forward IPv6 to specific NH | -| `End.DT4` | Endpoint with decap + IPv4 table lookup | Decap SRv6, lookup in VRF (BGP L3VPN) | -| `End.DT6` | Endpoint with decap + IPv6 table lookup | Decap SRv6, lookup IPv6 VRF | -| `End.DT46` | Endpoint with decap + IP table lookup | Decap SRv6, lookup IPv4 or IPv6 VRF | -| `End.DX2` | Endpoint with decap + L2 cross-connect | EVPN VPWS | -| `End.B6.Encaps` | Endpoint with SR policy encap | Re-encapsulate with a new SR policy | -| `End.BM` | Endpoint with SR in MPLS | SRv6 ↔ SR-MPLS interworking | - ---- - -## uSID — Compressed SRv6 - -Standard SRv6 SIDs = 128 bits = 16 bytes per segment. For many-segment paths, overhead is significant. **uSID (micro-SID)** compresses multiple SIDs into a single 128-bit address: - -``` -Standard SID: 2001:db8:0001:0000:0000:0000:0000:0000 (one node, one action) - -uSID: 2001:db8:0001:0002:0003:0000:0000:0000 - └─ locator ─┘└─u1─┘└─u2─┘└─u3─┘ - -Three micro-SIDs packed into one 128-bit address. -Each uSID = 16 bits (or 32 bits in some deployments). -Reduces overhead from 48 bytes (3 SIDs) to 16 bytes (1 SID with 3 uSIDs). -``` - -uSID is gaining rapid adoption (Cisco, Nokia, Juniper) — makes SRv6 overhead competitive with MPLS. - -**Datum relevance**: For a global backbone with multiple PoP hops, uSID compression is essential to keep packet overhead reasonable and competitive with traditional MPLS-based approaches. - ---- - -## SRv6 Encapsulation Modes - -### H.Encaps (Encapsulation) — Most Common - -``` -┌─────────────────────────────┐ -│ Outer IPv6 Header │ DA = first active SID -├─────────────────────────────┤ -│ SRH │ Segment list -├─────────────────────────────┤ -│ Original IPv4/IPv6 Packet │ Unchanged inner packet -└─────────────────────────────┘ - -Use case: PE routers in L3VPN, traffic engineering ingress -``` - -### H.Insert — SRH Insertion (no outer IPv6) - -``` -┌─────────────────────────────┐ -│ Original IPv6 Header │ DA updated to first SID -├─────────────────────────────┤ -│ SRH (inserted) │ Segment list -├─────────────────────────────┤ -│ Original IPv6 Payload │ -└─────────────────────────────┘ - -Use case: Transit IPv6 traffic, native SRv6 endpoints -Note: Cannot be used for IPv4 traffic -``` - ---- - -## SRv6 Control Plane - -### IGP SID Advertisement - -SRv6 SIDs are advertised via IS-IS or OSPF extensions: - -- **IS-IS**: SRv6 Locator TLV (TLV 27), SRv6 End SID Sub-TLV -- **OSPF**: SRv6 Locator LSA (Type 10), SRv6 SID Sub-TLV in Router-Info LSA - -### BGP for SRv6 Services - -BGP distributes service-layer SIDs (for L3VPN, EVPN): - -``` -BGP Update for SRv6 L3VPN: - NLRI: VPNv4 prefix (e.g., 10.0.0.0/24, RD 100:1) - Next-Hop: PE loopback (IPv6) - Attribute: Prefix-SID → SRv6 SID (e.g., End.DT4 SID) - -PE-2 receives this and knows: - "To reach 10.0.0.0/24 in VRF 100:1, - encapsulate with SRv6, set active SID to End.DT4 on PE-1" -``` - -### SR Policy - -An SR Policy is an explicitly defined segment list (path) installed by: -- **PCE** (Path Computation Element) — centralized TE via PCEP -- **BGP SR Policy** — distributed via BGP UPDATE -- **Headend static config** — manually defined -- **Controller** — SDN controller (relevant for Datum's programmatic approach) - -``` -SR Policy: - Endpoint: PE-2 (2001:db8:2::1) - Color: 100 (TE constraint identifier) - Candidate Paths: - Priority 10: [End.X@Node-A via link1, End.X@Node-C, End.DT4@PE-2] - Priority 20: [End.X@Node-B, End.DT4@PE-2] (backup) -``` - ---- - -## SRv6 TE — Traffic Engineering - -SRv6 TE uses **End.X SIDs** to steer traffic through specific links/nodes without RSVP-TE state: - -``` -Physical Topology: SR Policy (low-latency path): - - A ─── B ─── D Segment List: [End.X@A→C, End.X@C→D, End.DT4@D] - │ │ │ - └── C ─────┘ Packet takes A→C→D (low latency path) - even though shortest IGP path might be A→B→D -``` - -### SRv6 TE vs RSVP-TE - -| | RSVP-TE | SRv6 TE | -|---|---|---| -| State in network | Per-tunnel RSVP state on every node | No per-flow state anywhere | -| Signaling | RSVP PATH/RESV messages | IGP SID advertisement only | -| Scale | Thousands of tunnels = scalability problem | Millions of flows, no state | -| Failure recovery | RSVP FRR (fast reroute) | TI-LFA (Topology Independent LFA) | -| Flexibility | Tunnel-level TE | Per-packet source routing | - ---- - -## SRv6 for VPN Services - -### BGP SRv6 L3VPN - -``` -CE-1 → PE-1 (ingress): - Lookup CE-1's route in VRF → matches BGP route with SRv6 SID from PE-2 - Encapsulate: Outer IPv6 DA = End.DT4 SID of PE-2 - SRH (may be empty if no TE, or with TE waypoints) - Inner: original IPv4 packet from CE-1 - -P-nodes (transit): - Route on outer IPv6 DA (PE-2's locator prefix) - No MPLS, no VPN label awareness needed - -PE-2 (egress): - Receives packet, outer DA matches local End.DT4 SID - Decapsulate, remove SRH, lookup inner IPv4 in VRF - Forward to CE-2 - -Equivalent to: MPLS L3VPN with VPN label + transport label - But: no LDP, no RSVP, no MPLS labels at all -``` - -### BGP EVPN over SRv6 - -SRv6 EVPN provides L2VPN and L2/L3 services: - -- **End.DX2**: Decap + L2 cross-connect (EVPN VPWS) -- **End.DX2V**: Decap + VLAN-based L2 cross-connect -- **End.DT2M**: Decap + L2 table multicast (BUM traffic) - ---- - -## How Datum Uses SRv6 - -This is where Datum's architecture diverges from traditional telco/5G SRv6 deployments. Datum uses SRv6 for a fundamentally different use case: - -### SRv6 as Internet Backbone Overlay (Not 5G Transport) - -``` -Traditional SRv6 Deployment (Telco): - 5G RAN → 5G Core → SP Backbone (SRv6) → Internet - Focus: replacing MPLS in carrier infrastructure - -Datum's SRv6 Deployment (Open Network Cloud): - Alt Cloud / Agent → Datum PoP → SRv6 Backbone → Datum PoP → Destination - Focus: deterministic "fast lanes" across the internet for any application -``` - -### What Datum's SRv6 Backbone Provides - -| Capability | How SRv6 Enables It | -|---|---| -| **Deterministic routing** | SR Policies define explicit paths between PoPs — traffic doesn't take unpredictable internet routes | -| **VPC-style isolation** | SRv6 VPN services (End.DT4/DT6) provide tenant isolation without MPLS | -| **Observability** | SRv6 paths are auditable — you know exactly which nodes traffic traverses | -| **Performance optimization** | End.X SIDs steer traffic through low-latency paths | -| **Multi-tenant** | Different SR Policies per customer/agent — each gets their own "fast lane" | -| **Programmable** | Kubernetes controllers can dynamically create/modify SR Policies | -| **No per-flow state** | Stateless forwarding scales to millions of flows without state explosion | - -### The Controller-Driven Model - -Unlike traditional SP deployments where SR Policies are manually configured or PCE-computed, Datum's approach is **controller-driven** via the Kubernetes control plane: - -``` -Kubernetes Control Plane - │ - ├── Customer creates "Galactic VPC" resource (CRD) - ├── Controller reconciles: determines required PoP-to-PoP paths - ├── Computes SR Policies based on latency/topology constraints - ├── Programs SRv6 data plane at each PoP - └── Continuously monitors and adjusts (reconciliation loop) -``` - ---- - -## SRv6 Real-World Deployment Use Cases - -### Service Provider Core -- **Replace MPLS transport**: SRv6 locators in IS-IS replace LDP labels -- **TE without RSVP**: End.X SIDs + SR Policy replace RSVP-TE tunnels -- **Seamless migration**: SRv6/MPLS interworking (End.BM) for phased migration -- **Multi-domain TE**: BGP SR Policy across AS boundaries - -### Data Center Fabric -- **Replace VXLAN BGP EVPN underlay**: SRv6 for DC EVPN services -- **Service chaining (SFC)**: SRv6 encodes service function chains — each SID = a service function node -- **AI fabric optimization**: SRv6 uSID for deterministic RDMA traffic placement (emerging, Cisco active) - -### Open Network Cloud (Datum's Pattern) -- **Internet backbone overlay**: SRv6 between global PoPs for deterministic routing -- **Virtual private backbones in minutes**: Controller-provisioned SR Policies via CRDs -- **Tenant isolation**: SRv6 VPN services per customer without MPLS infrastructure -- **Multi-cloud connectivity**: SRv6 paths across cloud providers via Datum PoPs -- **Agent-addressable networking**: Each AI agent can have its own SR Policy / "fast lane" - -### Traditional Deployments -- **NTT Communications**: Full SRv6 backbone (Japan) -- **SoftBank**: SRv6 for 5G transport -- **China Mobile, China Telecom**: SRv6 backbone rollouts -- **Alibaba, Tencent**: SRv6 in DC fabrics -- **LinkedIn**: SRv6 in DC for service chaining and TE - ---- - -# Datum's Full-Stack Architecture - -## End-to-End Traffic Flow - -``` -AI Agent / Alt Cloud App / Developer Service - │ - │ QUIC tunnel (Iroh) — P2P encrypted, NAT-traversing - │ Identity: Ed25519 NodeId (zero trust, certificate-based) - │ -[Datum Edge PoP] - │ - │ Envoy proxy: TLS termination, WAF (Coraza), AI Gateway routing - │ HickoryDNS: Authoritative DNS resolution (17 locations) - │ Metrics: OTel export to Grafana Cloud - │ -[Datum SRv6 Backbone] - │ - │ SR Policy: deterministic path through global PoP mesh - │ End.X SIDs for TE, End.DT4/6 for VPN isolation - │ uSID compression for overhead efficiency - │ Spin bit monitoring for per-flow RTT telemetry - │ -[Destination Datum PoP] - │ - │ SRv6 decapsulation → VRF lookup → egress - │ Envoy proxy: reverse proxy to backend service - │ -Destination Service (any cloud, bare metal, on-prem) -``` - ---- - -## The Operational Tension: SRv6 + QUIC Encryption - -A critical architectural consideration that demonstrates deep understanding: - -**Problem**: SRv6 service chaining can steer QUIC traffic through security appliances (firewall → IDS → LB), but QUIC encryption means **DPI appliances in the chain cannot inspect payload**. The chain must handle flows at the connection level, not packet level. - -**Implications for Datum**: -- The SRv6 backbone can route and engineer QUIC tunnel traffic deterministically -- But the backbone is intentionally "blind" to tunnel contents (which is a *feature* for zero trust, not a bug) -- Observability relies on: spin bit RTT, flow-level telemetry (IPFIX), connection IDs, byte volumes, flow durations -- Security enforcement happens at the Envoy edge (WAF, bot detection, auth) rather than inline DPI in the backbone - -This is a deliberate design philosophy: **security at the edge, performance in the backbone**. - ---- - -## Envoy — The Edge Proxy - -**Envoy** is a CNCF-graduated, high-performance C++ proxy used by Datum as the global edge layer: - -| Role | Implementation | -|---|---| -| TLS termination | Envoy listener with TLS context | -| HTTP routing | HTTPProxy resources (Datum CRD) | -| WAF | Coraza (open-source, OWASP Core Rule Set) | -| AI traffic routing | Envoy AI Gateway (routes to GenAI backends) | -| Health checks | Built into Envoy | -| Metrics | Full OTel export to Grafana Cloud | -| Auth | Optional, configurable per-route | - -Deployed across 17+ global PoPs. The AI Gateway extension is particularly relevant — it handles routing from application clients to Generative AI services, which is a key Datum use case. - ---- - -## HickoryDNS - -Datum uses **HickoryDNS**, a Rust-based DNS client, server, and resolver built for safety and security. Served across 17 global locations as an authoritative DNS service. Rust implementation = memory-safe, no buffer overflow vulnerabilities that have historically plagued DNS infrastructure. - ---- - -## Crossplane - -**Crossplane** is Datum's framework for normalizing cloud provider integrations: - -``` -Datum Kubernetes Control Plane - │ - └── Crossplane Controllers - │ - ├── AWS Provider → provisions AWS resources via CRDs - ├── Azure Provider → provisions Azure resources via CRDs - ├── GCP Provider → provisions GCP resources via CRDs - └── Custom Providers → bare metal, edge locations -``` - -Key value: Datum's customers deploy across many clouds (the "alt cloud" ecosystem). Crossplane provides a **single, declarative API** to manage infrastructure across all of them, with continuous reconciliation ensuring desired state = actual state. - ---- - -## Galactic VPCs - -A planned Datum feature: **Galactic VPCs** — virtual private clouds that span multiple clouds and data centers. This maps directly to SRv6 L3VPN capabilities: - -- Each Galactic VPC = an SRv6 VPN with tenant-specific End.DT4/DT6 SIDs -- Spans across Datum's global PoPs -- Unified network management across hybrid/multi-cloud -- Real-time streaming telemetry -- Defined as Kubernetes CRDs — `kubectl apply` a VPC into existence - ---- - -# Interview Talking Points - -## Key Concepts to Demonstrate - -### 1. You Understand Datum's "Why" -The internet is fragmenting (sovereignty, regulation, alt-cloud explosion). Traditional private networks require dedicated teams and years to build. Datum makes SP-grade networking capabilities (peering, TE, private backbone, interconnection) available to every developer and AI agent via an open-source, API-first platform. - -### 2. You Understand the Three-Layer Architecture -- **Edge**: Envoy + Coraza WAF + AI Gateway (17+ PoPs) -- **Tunnels**: Iroh (QUIC P2P, hole punching, relay fallback, zero trust) -- **Backbone**: SRv6 overlay (deterministic routing, VPC isolation, telemetry) - -### 3. You Can Explain How SRv6 Differs from Traditional SP Use -Datum uses SRv6 not for 5G transport but for **internet backbone programmability** — an open-source network cloud where SR Policies are controller-driven via Kubernetes CRDs, not manually provisioned or PCE-computed carrier tunnels. - -### 4. You Know Why QUIC (Not TCP) for Tunnels -Connection migration (survives network changes), built-in encryption (relay can't inspect), stream multiplexing (independent flows), userspace implementation (rapid iteration), NAT traversal compatibility (UDP-based). - -### 5. You Can Articulate the SRv6 + QUIC Tension -SRv6 provides deterministic routing and service chaining, but QUIC encryption makes inline DPI impossible. Datum's design philosophy: security at the edge (Envoy/WAF), performance in the backbone (SRv6 TE). The backbone is intentionally blind to payload — zero trust. - -### 6. You Understand the Control Plane -Kubernetes CRDs + Crossplane for multi-cloud normalization. Reconciliation loops. GitOps-compatible. LLM-friendly API surface. KEP-4080 for generic control planes without container orchestration semantics. - -### 7. You Know the Team's Lineage -Founded by Packet/Equinix/Voxel/Fastly/StackPath veterans. These are people who built bare-metal cloud automation, ran global data center platforms, and deeply understand peering, interconnection, and SP-grade networking. - -### 8. Industry Context — SRv6 Momentum Beyond Telco -SRv6 is expanding from 5G/SP deployments into AI infrastructure (GPU fabric optimization, RDMA traffic placement, cross-DC scale-across architectures). Cisco is actively promoting SRv6 uSID for AI workloads. Datum is part of this broader trend of SRv6 moving into non-traditional use cases. - ---- - -# Key RFCs & References - -## QUIC -| RFC | Title | -|---|---| -| RFC 8999 | Version-Independent Properties of QUIC | -| RFC 9000 | QUIC: A UDP-Based Multiplexed and Secure Transport (**core spec**) | -| RFC 9001 | Using TLS to Secure QUIC | -| RFC 9002 | QUIC Loss Detection and Congestion Control | -| RFC 9221 | Unreliable Datagram Extension to QUIC (DATAGRAM frames) | -| RFC 9250 | DNS over Dedicated QUIC Connections (DoQ) | -| RFC 9369 | QUIC Version 2 | -| RFC 9484 | Proxying IP in HTTP (CONNECT-IP) | -| draft-ietf-quic-multipath | QUIC Multipath (active draft — relevant to Iroh) | - -## MASQUE -| RFC | Title | -|---|---| -| RFC 9297 | HTTP Datagrams and the Capsule Protocol | -| RFC 9298 | Proxying UDP in HTTP (CONNECT-UDP) | -| RFC 9484 | Proxying IP in HTTP (CONNECT-IP) | -| RFC 9412 | The MASQUE Problem Statement | - -## SRv6 -| RFC | Title | -|---|---| -| RFC 8402 | Segment Routing Architecture | -| RFC 8754 | IPv6 Segment Routing Header (SRH) | -| RFC 8814 | Signaling MSD using BGP-LS | -| RFC 8986 | SRv6 Network Programming (**core endpoint behaviors**) | -| RFC 9252 | BGP Overlay Services Based on SRv6 (L3VPN, EVPN) | -| RFC 9259 | OAM for SRv6 | -| draft-ietf-spring-srv6-srh-compression | uSID / SRv6 compression (active draft) | - -## Datum-Specific References -| Reference | Description | -|---|---| -| [datum.net](https://datum.net) | Datum Cloud — product, docs, blog | -| [github.com/datum-cloud](https://github.com/datum-cloud) | Open source repos (AGPLv3) | -| [datum.net/blog/every-agent-needs-an-edge](https://datum.net/blog/every-agent-needs-an-edge/) | "Splinternet" thesis and architecture overview (Feb 2026) | -| [datum.net/blog/control-plane-for-modern-service-providers](https://datum.net/blog/control-plane-for-modern-service-providers/) | K8s control plane design rationale | -| [docs.iroh.computer](https://docs.iroh.computer) | Iroh documentation (QUIC connectivity library) | -| [iroh.computer/blog/iroh-on-QUIC-multipath](https://iroh.computer/blog/iroh-on-QUIC-multipath) | QUIC Multipath work in Quinn/Iroh | -| [crossplane.io](https://crossplane.io) | Crossplane — cloud-native control plane framework | - -## General -| Reference | Description | -|---|---| -| [quicwg.org](https://quicwg.org) | IETF QUIC Working Group | -| [segment-routing.net](https://segment-routing.net) | SRv6/SR-MPLS resources | -| Wireshark | Full QUIC and SRv6 dissectors (v3.3+) | -| Quinn | Pure-Rust QUIC implementation (basis of Iroh) | -| FRRouting (FRR) | Open-source routing suite with SRv6 support | -| VPP (fd.io) | High-performance dataplane with SRv6 and QUIC support | From 7d3ca00a634964837da6d28a55222dcc3f19564c Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:23:06 -0500 Subject: [PATCH 18/27] Replace REST API reference with operational guide --- rest-api.md | 190 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 rest-api.md diff --git a/rest-api.md b/rest-api.md new file mode 100644 index 0000000..d5c8022 --- /dev/null +++ b/rest-api.md @@ -0,0 +1,190 @@ +# REST API Cheat Sheet + +> **Applies to:** HTTP-based JSON APIs and general REST conventions +> **Last reviewed:** 2026-07-14 + +REST is an architectural style, not a wire protocol. APIs vary, so treat these as interoperable defaults rather than universal rules. + +## HTTP methods + +| Method | Typical use | Safe | Idempotent | +|---|---|---:|---:| +| `GET` | Retrieve a representation | Yes | Yes | +| `HEAD` | Retrieve headers only | Yes | Yes | +| `POST` | Create or trigger processing | No | No | +| `PUT` | Replace a resource at a known URI | No | Yes | +| `PATCH` | Partially update a resource | No | Depends on patch semantics | +| `DELETE` | Remove a resource | No | Yes | +| `OPTIONS` | Discover communication options | Yes | Yes | + +**Safe** means the method is intended not to change server state. **Idempotent** means repeating the same request has the same intended effect as sending it once. + +## Common status codes + +| Code | Meaning | Typical use | +|---:|---|---| +| `200` | OK | Successful read or update | +| `201` | Created | Resource created; return a `Location` header when practical | +| `202` | Accepted | Asynchronous work accepted but not finished | +| `204` | No Content | Successful request with no response body | +| `304` | Not Modified | Conditional request cache hit | +| `400` | Bad Request | Malformed syntax or invalid request structure | +| `401` | Unauthorized | Authentication is missing or invalid | +| `403` | Forbidden | Identity is known but lacks permission | +| `404` | Not Found | Resource does not exist or is intentionally concealed | +| `409` | Conflict | State conflict, duplicate, or failed concurrency condition | +| `412` | Precondition Failed | `If-Match` or another precondition failed | +| `415` | Unsupported Media Type | Unsupported request content type | +| `422` | Unprocessable Content | Semantically invalid request | +| `429` | Too Many Requests | Rate limit exceeded | +| `500` | Internal Server Error | Unexpected server failure | +| `502` | Bad Gateway | Invalid upstream response | +| `503` | Service Unavailable | Temporarily unavailable or overloaded | +| `504` | Gateway Timeout | Upstream timed out | + +## Request example + +```http +POST /v1/users HTTP/1.1 +Host: api.example.com +Authorization: Bearer +Content-Type: application/json +Accept: application/json +Idempotency-Key: + +{ + "name": "Jane Doe", + "email": "jane@example.com" +} +``` + +## Response example + +```http +HTTP/1.1 201 Created +Content-Type: application/json +Location: /v1/users/123 +ETag: "7b9f6a" + +{ + "id": "123", + "name": "Jane Doe", + "email": "jane@example.com" +} +``` + +## curl patterns + +```bash +curl --fail-with-body --silent --show-error \ + --request GET \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer ' \ + 'https://api.example.com/v1/users?limit=50' +``` + +```bash +curl --fail-with-body --silent --show-error \ + --request POST \ + --header 'Authorization: Bearer ' \ + --header 'Content-Type: application/json' \ + --data @request.json \ + https://api.example.com/v1/users +``` + +Capture headers and body separately when troubleshooting: + +```bash +curl --dump-header response.headers \ + --output response.json \ + --write-out '%{http_code}\n' \ + https://api.example.com/health +``` + +## Resource and URL design + +- Use stable nouns: `/users/123`, not `/getUser?id=123`. +- Keep identifiers opaque to clients. +- Use query parameters for filtering, sorting, pagination, and optional projections. +- Avoid deeply nested resource paths. +- Do not encode secrets or sensitive data in URLs; URLs are commonly logged. +- Return absolute or well-defined relative links when clients need navigation. + +Example: + +```text +GET /v1/incidents?status=open&severity=critical&sort=-created_at&limit=50 +``` + +## Pagination + +Cursor pagination is generally more stable than offsets for changing datasets: + +```json +{ + "items": [], + "next_cursor": "opaque-value" +} +``` + +Do not promise a meaningful total count unless the service can provide it efficiently and consistently. + +## Concurrency and retries + +Use ETags and conditional requests to prevent lost updates: + +```http +GET /v1/config/123 +ETag: "version-7" +``` + +```http +PUT /v1/config/123 +If-Match: "version-7" +``` + +Retry only when the operation is safe or idempotent, or when the API supports an idempotency key. Use bounded exponential backoff with jitter. Honor `Retry-After` on `429` and `503` responses. + +## Authentication and authorization + +- Require HTTPS. +- Keep authentication separate from authorization. +- Validate token issuer, audience, signature, expiration, and intended scopes. +- Prefer short-lived credentials. +- Never log bearer tokens, session cookies, API keys, passwords, or full sensitive payloads. +- Apply authorization at the resource and action level, not only at the route level. + +## Error format + +Use one consistent machine-readable structure. RFC 9457 Problem Details is a strong default: + +```json +{ + "type": "https://api.example.com/problems/invalid-parameter", + "title": "Invalid parameter", + "status": 422, + "detail": "limit must be between 1 and 100", + "instance": "/v1/users?limit=1000" +} +``` + +## Observability + +Include or propagate: + +- A request or correlation ID. +- Trace context. +- Structured logs with secret redaction. +- Latency, throughput, saturation, and error metrics. +- Upstream dependency timing. + +## Versioning and compatibility + +Prefer additive changes where possible. Removing fields, changing field meaning, tightening validation, or altering enum behavior can break clients even when the URL version is unchanged. Publish a deprecation timeline and instrument usage before removal. + +## References + +- [HTTP Semantics — RFC 9110](https://www.rfc-editor.org/rfc/rfc9110) +- [HTTP Caching — RFC 9111](https://www.rfc-editor.org/rfc/rfc9111) +- [Problem Details for HTTP APIs — RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) +- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html) From 073f63630d3ded5e956a20adc4cb327ae5da47c3 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:23:10 -0500 Subject: [PATCH 19/27] Remove superseded REST API file --- RESTful.md | 112 ----------------------------------------------------- 1 file changed, 112 deletions(-) delete mode 100644 RESTful.md diff --git a/RESTful.md b/RESTful.md deleted file mode 100644 index cabe225..0000000 --- a/RESTful.md +++ /dev/null @@ -1,112 +0,0 @@ -# RESTful API Cheat Sheet - -RESTful APIs (Representational State Transfer) are an architectural style for designing networked applications. They use HTTP requests to access and use data. RESTful APIs are stateless, meaning that each request from a client contains all the information needed to process the request. - -- **Key Operations (HTTP Methods)**: - - GET: Retrieve data from a server. - - POST: Send data to a server. - - PUT: Update data on a server. - - DELETE: Remove data from a server. - -## Basic Components - -- **Endpoints**: URLs where API operations are accessed. -- **HTTP Methods**: Define action types (GET, POST, PUT, DELETE). -- **Headers**: Convey metadata for the HTTP request and response. -- **Body**: Contains data sent to or received from the server (typically in JSON format). -- **Status Codes**: Indicate the result of the HTTP request (e.g., 200 OK, 404 Not Found). - -## Common HTTP Methods - -- **GET** - - Used to retrieve data from a server. - - Example: `GET /users` retrieves a list of users. - -- **POST** - - Used to send data to a server. - - Example: `POST /users` with a user object in the request body to create a new user. - -- **PUT** - - Used to update existing data on a server. - - Example: `PUT /users/123` with updated user data in the request body. - -- **DELETE** - - Used to delete data from a server. - - Example: `DELETE /users/123` deletes the user with ID 123. - -## RESTful API Design Best Practices - -- **API Gateway Usage**: Use an API gateway for management, authentication, and analytics. -- **Be Consistent**: Use a consistent naming convention and format. -- **Cache Data to Improve Performance**: Utilize HTTP caching mechanisms for better performance. -- **Consistent Responses**: Use a consistent format for all API responses. -- **Content Negotiation**: Support multiple media types for requests and responses (e.g., application/json, application/xml). -- **Cross-Origin Resource Sharing (CORS)**: Properly configure CORS if your API is to be accessed from different domains. -- **Deprecation Policy**: Clearly communicate any deprecations in API functionality. -- **Documentation**: Provide clear and comprehensive documentation for your API. -- **Environment-Based Configuration**: Separate configuration from code, especially for different environments (development, staging, production). -- **Error Handling Standardization**: Standardize the structure of error messages. -- **Filtering, Sorting, and Searching**: Allow users to filter, sort, and search data through query parameters. -- **Follow REST Constraints**: Adhere to REST constraints such as client-server architecture, statelessness, and cacheability. -- **Handle Errors Gracefully**: Provide clear error messages and appropriate HTTP status codes. -- **Implement ETags for Optimistic Concurrency Control**: Utilize ETags for managing simultaneous updates. -- **Internationalization and Localization**: Consider supporting multiple languages and regional data formats. -- **Limit Resource Nesting**: Avoid deeply nested resources. Aim for a maximum of three levels. -- **Monitoring and Logging**: Implement monitoring and logging to track API usage and errors. -- **Pagination**: Implement pagination for responses with large data sets. -- **Partial Responses**: Allow clients to request only the fields they need. -- **Rate Limiting**: Implement rate limiting to prevent abuse and maintain service availability. -- **Resource Identification in Requests**: Ensure resources are clearly and uniquely identified by their URIs. -- **Respect Privacy and Data Regulations**: Comply with data protection regulations like GDPR. -- **Security Audits and Updates**: Regularly audit and update security measures. -- **Security**: Implement authentication, authorization, and data encryption. -- **Standardize Timestamps and Time Zones**: Use a consistent format for timestamps and consider time zone implications. -- **Statelessness**: Ensure that each API request can be processed independently. -- **Support for HEAD and OPTIONS Methods**: Implement these methods for resource metadata and communication options. -- **Use HATEOAS (Hypertext As The Engine Of Application State)**: Allow navigation through the API via hyperlinks. -- **Use HTTP Methods Appropriately**: Align actions with the correct HTTP methods. -- **Use Nouns in Endpoint Paths**: Prefer `/users` over `/getUsers`. -- **Use of HTTP Status Codes**: Appropriately use HTTP status codes to indicate the outcome of API requests. -- **Use of Query Parameters for Optional Features**: Utilize query parameters for sorting, filtering, and pagination. -- **Use Plural Nouns for Consistency**: Prefer `/items` over `/item` for resource names. -- **Use SSL/TLS for Secure Communication**: Always use HTTPS to secure data in transit. -- **Use Sub-Resources for Relations**: For hierarchical data, use sub-resources (e.g., `/users/{id}/posts`). -- **Use Webhooks for Event Notifications**: Implement webhooks to notify clients of events. -- **Versioning**: Version your API to manage changes and maintain backward compatibility. - -## Response Status Codes - -- **200 OK**: The request has succeeded. -- **201 Created**: A new resource has been created. -- **400 Bad Request**: The server cannot process the request due to a client error. -- **401 Unauthorized**: Authentication is required and has failed or not been provided. -- **403 Forbidden**: The client does not have permission to access the requested resource. -- **404 Not Found**: The requested resource was not found. -- **500 Internal Server Error**: An unexpected condition was encountered on the server. - -## Sample RESTful API Request - -- **GET Request Example** -``` - GET /api/users HTTP/1.1 - Host: example.com - Accept: application/json -``` - -- **POST Request Example** -``` -POST /api/users HTTP/1.1 -Host: example.com -Content-Type: application/json - -{ - "name": "John Doe", - "email": "john@example.com" -} -``` - - -#### Tools for Testing RESTful APIs -- **Postman**: A popular tool for testing API endpoints. -- **Curl**: A command-line tool for sending HTTP requests. -- **Swagger**: Useful for API documentation and testing. From 2b899a87aa0dcc66e2b052c38799070d338725af Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:23:25 -0500 Subject: [PATCH 20/27] Finalize repository index after cleanup --- README.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 4a392ec..746087e 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,6 @@ Practical quick-reference notes for network engineering, Linux operations, cloud | OSPF | [ospf.md](ospf.md) | | TCP | [tcp.md](tcp.md) | | UDP | [udp.md](udp.md) | -| QUIC, MASQUE, and SRv6 | [quic-masque-srv6.md](quic-masque-srv6.md) | ## Network platforms and routing software @@ -94,8 +93,8 @@ Practical quick-reference notes for network engineering, Linux operations, cloud Accuracy-sensitive documents should include an **Applies to** line and a **Last reviewed** date. A review date means the examples received a documentation review; it does not guarantee compatibility with every release or environment. -Repository quality checks validate Markdown and links on pull requests and changes to `main`. See [CONTRIBUTING.md](CONTRIBUTING.md) and [STYLE_GUIDE.md](STYLE_GUIDE.md) before adding or substantially rewriting a sheet. +Repository quality checks validate the maintained documentation surface on pull requests and changes to `main`. See [CONTRIBUTING.md](CONTRIBUTING.md) and [STYLE_GUIDE.md](STYLE_GUIDE.md) before adding or substantially rewriting a sheet. ## License -Content is available under the [MIT License](LICENSE). \ No newline at end of file +Content is available under the [MIT License](LICENSE). From 089c294ea7feacab5a81c98df2af93820b958233 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:23:38 -0500 Subject: [PATCH 21/27] Scope documentation checks to maintained files --- .github/workflows/docs-quality.yml | 33 ++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml index 1e165cf..f282680 100644 --- a/.github/workflows/docs-quality.yml +++ b/.github/workflows/docs-quality.yml @@ -17,11 +17,22 @@ jobs: - name: Check out repository uses: actions/checkout@v4 - - name: Lint Markdown + - name: Lint maintained Markdown uses: DavidAnson/markdownlint-cli2-action@v20 with: globs: | - **/*.md + README.md + CONTRIBUTING.md + STYLE_GUIDE.md + arista.md + azure.md + cisco.md + docker.md + gcloud.md + iptables.md + kubernetes.md + rest-api.md + terraform.md links: runs-on: ubuntu-latest @@ -29,8 +40,22 @@ jobs: - name: Check out repository uses: actions/checkout@v4 - - name: Check links + - name: Check maintained documentation links uses: lycheeverse/lychee-action@v2 with: - args: --verbose --no-progress './**/*.md' + args: >- + --verbose + --no-progress + README.md + CONTRIBUTING.md + STYLE_GUIDE.md + arista.md + azure.md + cisco.md + docker.md + gcloud.md + iptables.md + kubernetes.md + rest-api.md + terraform.md fail: true From 21f8ec6162ddb8015af1dc37eca5fb770db89668 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:26:56 -0500 Subject: [PATCH 22/27] Fix README Git reference --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 746087e..60a87b6 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ Practical quick-reference notes for network engineering, Linux operations, cloud | Topic | Reference | |---|---| -| Git | [git.md](git.md) | +| Git | [github.md](github.md) | | Kafka | [kafka.md](kafka.md) | | REST APIs | [rest-api.md](rest-api.md) | | SQL | [sql.md](sql.md) | From ea376125a37c3f1fdc1cfdea80b5ff6dae59124c Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:27:01 -0500 Subject: [PATCH 23/27] Focus Markdown lint on correctness rules --- .markdownlint.json | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/.markdownlint.json b/.markdownlint.json index 5a092df..4ab3dc7 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -1,8 +1,12 @@ { - "default": true, - "MD013": false, - "MD024": false, - "MD033": false, - "MD036": false, - "MD041": true + "default": false, + "MD010": true, + "MD011": true, + "MD018": true, + "MD019": true, + "MD020": true, + "MD021": true, + "MD023": true, + "MD042": true, + "MD047": true } From a72976c07b9b234d8201abd93573794cd94f9438 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:27:09 -0500 Subject: [PATCH 24/27] Make documentation checks deterministic --- .github/workflows/docs-quality.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml index f282680..b051fae 100644 --- a/.github/workflows/docs-quality.yml +++ b/.github/workflows/docs-quality.yml @@ -44,6 +44,7 @@ jobs: uses: lycheeverse/lychee-action@v2 with: args: >- + --offline --verbose --no-progress README.md From 8e3ea6422a7e8821a17f976654a1f8cf2b405077 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:28:08 -0500 Subject: [PATCH 25/27] Use deterministic Markdown validation --- .github/workflows/docs-quality.yml | 73 +++++++++++++++++++++++------- 1 file changed, 56 insertions(+), 17 deletions(-) diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml index b051fae..20d4ddf 100644 --- a/.github/workflows/docs-quality.yml +++ b/.github/workflows/docs-quality.yml @@ -11,28 +11,67 @@ permissions: contents: read jobs: - markdownlint: + markdown-structure: runs-on: ubuntu-latest steps: - name: Check out repository uses: actions/checkout@v4 - - name: Lint maintained Markdown - uses: DavidAnson/markdownlint-cli2-action@v20 - with: - globs: | - README.md - CONTRIBUTING.md - STYLE_GUIDE.md - arista.md - azure.md - cisco.md - docker.md - gcloud.md - iptables.md - kubernetes.md - rest-api.md - terraform.md + - name: Validate maintained Markdown structure + shell: bash + run: | + python - <<'PY' + from pathlib import Path + import re + import sys + + files = [ + "README.md", + "CONTRIBUTING.md", + "STYLE_GUIDE.md", + "arista.md", + "azure.md", + "cisco.md", + "docker.md", + "gcloud.md", + "iptables.md", + "kubernetes.md", + "rest-api.md", + "terraform.md", + ] + + errors = [] + for filename in files: + path = Path(filename) + if not path.is_file(): + errors.append(f"{filename}: file is missing") + continue + + text = path.read_text(encoding="utf-8") + lines = text.splitlines() + h1_count = sum(1 for line in lines if line.startswith("# ")) + + if h1_count != 1: + errors.append(f"{filename}: expected exactly one H1, found {h1_count}") + if not text.endswith("\n"): + errors.append(f"{filename}: file must end with a newline") + if text.count("```") % 2: + errors.append(f"{filename}: unbalanced fenced code blocks") + + for number, line in enumerate(lines, start=1): + if "\t" in line: + errors.append(f"{filename}:{number}: tab character found") + if re.match(r"^#{1,6}[^ #]", line): + errors.append(f"{filename}:{number}: heading marker needs a space") + if re.search(r"\[[^\]]*\]\(\s*\)", line): + errors.append(f"{filename}:{number}: empty Markdown link") + + if errors: + print("\n".join(errors)) + sys.exit(1) + + print(f"Validated {len(files)} maintained Markdown files.") + PY links: runs-on: ubuntu-latest From fbcf5bb63cb719fc7245f8a992ca49cf4d2f412f Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:28:13 -0500 Subject: [PATCH 26/27] Remove unused Markdown lint configuration --- .markdownlint.json | 12 ------------ 1 file changed, 12 deletions(-) delete mode 100644 .markdownlint.json diff --git a/.markdownlint.json b/.markdownlint.json deleted file mode 100644 index 4ab3dc7..0000000 --- a/.markdownlint.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "default": false, - "MD010": true, - "MD011": true, - "MD018": true, - "MD019": true, - "MD020": true, - "MD021": true, - "MD023": true, - "MD042": true, - "MD047": true -} From 73179a705f27585997a6132c83eb15d2622754c1 Mon Sep 17 00:00:00 2001 From: Anton Flor Date: Tue, 14 Jul 2026 16:28:55 -0500 Subject: [PATCH 27/27] Validate stable Markdown invariants --- .github/workflows/docs-quality.yml | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/.github/workflows/docs-quality.yml b/.github/workflows/docs-quality.yml index 20d4ddf..2fca521 100644 --- a/.github/workflows/docs-quality.yml +++ b/.github/workflows/docs-quality.yml @@ -48,21 +48,20 @@ jobs: continue text = path.read_text(encoding="utf-8") - lines = text.splitlines() - h1_count = sum(1 for line in lines if line.startswith("# ")) + if not text.strip(): + errors.append(f"{filename}: file is empty") + continue - if h1_count != 1: - errors.append(f"{filename}: expected exactly one H1, found {h1_count}") - if not text.endswith("\n"): - errors.append(f"{filename}: file must end with a newline") - if text.count("```") % 2: - errors.append(f"{filename}: unbalanced fenced code blocks") + first_content_line = next( + (line for line in text.splitlines() if line.strip()), + "", + ) + if not first_content_line.startswith("# "): + errors.append(f"{filename}: first content line must be an H1") + if "\x00" in text: + errors.append(f"{filename}: NUL byte found") - for number, line in enumerate(lines, start=1): - if "\t" in line: - errors.append(f"{filename}:{number}: tab character found") - if re.match(r"^#{1,6}[^ #]", line): - errors.append(f"{filename}:{number}: heading marker needs a space") + for number, line in enumerate(text.splitlines(), start=1): if re.search(r"\[[^\]]*\]\(\s*\)", line): errors.append(f"{filename}:{number}: empty Markdown link")