{"id":13646242,"url":"https://github.com/firecracker-microvm/firectl","last_synced_at":"2025-05-15T12:03:18.366Z","repository":{"id":37742974,"uuid":"160432801","full_name":"firecracker-microvm/firectl","owner":"firecracker-microvm","description":"firectl is a command-line tool to run Firecracker microVMs","archived":false,"fork":false,"pushed_at":"2025-04-16T23:24:10.000Z","size":322,"stargazers_count":515,"open_issues_count":15,"forks_count":74,"subscribers_count":21,"default_branch":"main","last_synced_at":"2025-04-21T19:01:43.761Z","etag":null,"topics":["aws","cli","firecracker","firecracker-vm","golang","virtual-machine"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/firecracker-microvm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-04T23:39:49.000Z","updated_at":"2025-04-17T01:33:37.000Z","dependencies_parsed_at":"2024-01-07T09:39:54.308Z","dependency_job_id":"972b6143-bad3-478c-b772-73af37ab2ef4","html_url":"https://github.com/firecracker-microvm/firectl","commit_stats":{"total_commits":93,"total_committers":28,"mean_commits":"3.3214285714285716","dds":0.8172043010752688,"last_synced_commit":"061ffe731a20adab2a8542d1de65a9963ca93c55"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firecracker-microvm%2Ffirectl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firecracker-microvm%2Ffirectl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firecracker-microvm%2Ffirectl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/firecracker-microvm%2Ffirectl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/firecracker-microvm","download_url":"https://codeload.github.com/firecracker-microvm/firectl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337612,"owners_count":22054253,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cli","firecracker","firecracker-vm","golang","virtual-machine"],"created_at":"2024-08-02T01:02:51.270Z","updated_at":"2025-05-15T12:03:18.340Z","avatar_url":"https://github.com/firecracker-microvm.png","language":"Go","readme":"firectl\n===\n\n[![Build status](https://badge.buildkite.com/92fe02b4bd9564be0f7ea21d1ee782f6a6fe55cbd5465e3480.svg?branch=master)](https://buildkite.com/firecracker-microvm/firectl)\n\nFirectl is a basic command-line tool that lets you run arbitrary\nFirecracker MicroVMs via the command line. This lets you run a fully\nfunctional Firecracker MicroVM, including console access, read/write\naccess to filesystems, and network connectivity.\n\nBuilding\n---\n\nThe default Makefile rule executes `go build` and relies on the Go toolchain\ninstalled on your computer.\n_We use [go modules](https://github.com/golang/go/wiki/Modules), and building\nrequires Go 1.23 or newer._\n\nIf you do not have a new-enough Go toolchain installed, you can use `make\nbuild-in-docker`.  This rule creates a temporary Docker container which builds\nand copies the binary to your current directory.\n\nUsage\n---\n\nYou'll need to have a\n[firecracker](https://github.com/firecracker-microvm/firecracker) build, as well\nas an uncompressed Linux kernel image (`vmlinux`) and root filesystem image.\n\nBy default, firectl searches `PATH` for the firecracker binary. The location of\nthe kernel and filesystem image must be provided explicitly.\n\n```\nUsage:\n  firectl [OPTIONS]\n\nApplication Options:\n      --firecracker-binary=     Path to firecracker binary\n      --kernel=                 Path to the kernel image (default: ./vmlinux)\n      --kernel-opts=            Kernel commandline (default: ro console=ttyS0 noapic reboot=k panic=1 pci=off nomodules)\n      --root-drive=             Path to root disk image, optionally suffixed with :ro or :rw\n      --root-partition=         Root partition UUID\n      --add-drive=              Path to additional drive, suffixed with :ro or :rw, can be specified multiple times\n      --tap-device=             NIC info, specified as DEVICE/MAC\n      --vsock-device=           Vsock interface, specified as PATH:CID. Multiple OK\n      --vmm-log-fifo=           FIFO for firecracker logs\n      --log-level=              vmm log level (default: Debug)\n      --metrics-fifo=           FIFO for firecracker metrics\n  -t, --disable-smt             Disable CPU Simultaneous Multithreading\n  -c, --ncpus=                  Number of CPUs (default: 1)\n      --cpu-template=           Firecracker CPU Template (C3 or T2)\n  -m, --memory=                 VM memory, in MiB (default: 512)\n      --metadata=               Firecracker Metadata for MMDS (json)\n  -l, --firecracker-log=        pipes the fifo contents to the specified file\n  -s, --socket-path=            path to use for firecracker socket, defaults to a unique file in in the first existing directory from {$HOME, $TMPDIR, or /tmp}\n  -d, --debug                   Enable debug output\n\nHelp Options:\n  -h, --help                    Show this help message\n```\n\nExample\n---\n\n```\nfirectl \\\n  --kernel=~/bin/vmlinux \\\n  --root-drive=/images/image-debootstrap.img -t \\\n  --cpu-template=T2 \\\n  --firecracker-log=~/firecracker-vmm.log \\\n  --kernel-opts=\"console=ttyS0 noapic reboot=k panic=1 pci=off nomodules rw\" \\\n  --vsock-device=root:3 \\\n  --metadata='{\"foo\":\"bar\"}'\n```\n\nGetting Started on AWS\n---\n\n- Create an `m5d.metal` instance using Amazon Linux 2\n- Get firectl binary:\n\n  ```\n  curl -Lo firectl https://firectl-release.s3.amazonaws.com/firectl-v0.1.0\n  curl -Lo firectl.sha256 https://firectl-release.s3.amazonaws.com/firectl-v0.1.0.sha256\n  sha256sum -c firectl.sha256\n  chmod +x firectl\n  ```\n\n- Get Firecracker binary:\n\n  ```\n  curl -Lo firecracker https://github.com/firecracker-microvm/firecracker/releases/download/v0.16.0/firecracker-v0.16.0\n  chmod +x firecracker\n  sudo mv firecracker /usr/local/bin/firecracker\n  ```\n\n- Give read/write access to KVM:\n\n  ```\n  sudo setfacl -m u:${USER}:rw /dev/kvm\n  ```\n\n- Download kernel and root filesystem:\n\n  ```\n  curl -fsSL -o hello-vmlinux.bin https://s3.amazonaws.com/spec.ccfc.min/img/hello/kernel/hello-vmlinux.bin\n  curl -fsSL -o hello-rootfs.ext4 https://s3.amazonaws.com/spec.ccfc.min/img/hello/fsfiles/hello-rootfs.ext4\n  ```\n\n- Create microVM:\n\n  ```\n  ./firectl \\\n    --kernel=hello-vmlinux.bin \\\n    --root-drive=hello-rootfs.ext4\n  ```\n\nTesting\n---\nBy default the tests require the firectl binary to be built and a kernel image\nto be present. The integration tests look for the binary and kernel image in\nthe root directory. By default it will look for vmlinux kernel image. This can\nbe overwritten by setting the environment variable `KERNELIMAGE` to the desired\npath. To disable these tests simply set the environment variable\n`SKIP_INTEG_TEST=1`.\n\nQuestions?\n---\n\nPlease use\n[GitHub issues](https://github.com/firecracker-microvm/firectl/issues)\nto report problems, discuss roadmap items, or make feature requests.\n\nIf you've discovered an issue that may have security implications to\nusers or developers of this software, please do not report it using\nGitHub issues, but instead follow\n[Firecracker's security reporting guidelines](https://github.com/firecracker-microvm/firecracker/blob/main/SECURITY.md).\n\nOther discussion: For general discussion, please get in touch with the [Firecracker community.](https://github.com/firecracker-microvm/firecracker?tab=readme-ov-file#faq--contact).\n","funding_links":[],"categories":["Go","Projects"],"sub_categories":["Security"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirecracker-microvm%2Ffirectl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffirecracker-microvm%2Ffirectl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffirecracker-microvm%2Ffirectl/lists"}