From 95e2858b3997e4c0807a919cdb586f3a0d3b731b Mon Sep 17 00:00:00 2001 From: William Theaker Date: Thu, 9 May 2024 14:48:15 -0400 Subject: [PATCH 1/2] Minor doc improvements. --- .gitignore | 2 +- README.md | 6 +++--- cmd/vfkit/root.go | 4 ++-- doc/missing-vz-api.md | 9 ++++----- doc/quickstart.md | 18 +++++++++--------- doc/usage.md | 12 ++++++------ pkg/cmdline/cmdline.go | 6 +++--- pkg/config/bootloader.go | 2 +- 8 files changed, 29 insertions(+), 30 deletions(-) diff --git a/.gitignore b/.gitignore index 8505faff..1223a148 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,2 @@ /out - +**/.DS_Store diff --git a/README.md b/README.md index 778996d1..e8c5cbcb 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ -vfkit - Simple command line tool to start VMs through virtualization framework +vfkit - Simple command line tool to start VMs through the macOS Virtualization framework ==== ### Introduction -vfkit offers a command-line interface to start virtual machines using virtualization framework. +vfkit offers a command-line interface to start virtual machines using the [macOS Virtualization framework](https://developer.apple.com/documentation/virtualization). It also provides a `github.com/crc-org/vfkit/pkg/config` go package. -This package provides a native go API to generate the vfkit command line. +This package provides a native Go API to generate the vfkit command line. ### Installation diff --git a/cmd/vfkit/root.go b/cmd/vfkit/root.go index eea2f9f2..b86d5668 100644 --- a/cmd/vfkit/root.go +++ b/cmd/vfkit/root.go @@ -13,8 +13,8 @@ var opts = &cmdline.Options{} var rootCmd = &cobra.Command{ Use: "vfkit", - Short: "vfkit is a simple hypervisor using Apple's virtualization framework", - Long: `A hypervisor written in Go using Apple's virtualization framework to run linux virtual machines. + Short: "vfkit is a simple hypervisor using Apple's Virtualization framework", + Long: `A hypervisor written in Go using Apple's Virtualization framework to run Linux virtual machines. Complete documentation is available at https://github.com/crc-org/vfkit`, RunE: func(_ *cobra.Command, _ []string) error { if len(opts.LogLevel) > 0 { diff --git a/doc/missing-vz-api.md b/doc/missing-vz-api.md index 2ff97963..14faa596 100644 --- a/doc/missing-vz-api.md +++ b/doc/missing-vz-api.md @@ -1,13 +1,13 @@ -# Missing API +# Missing APIs -This document contains a non-exhaustive list of API which are not used/supported by `vfkit`, but which would be useful to have. +This document contains a non-exhaustive list of APIs not currently used/supported by `vfkit`, but could be useful to have. -## non-vz API +## non-vz APIs - start vfkit process (integrating with https://pkg.go.dev/os/exec ) - get VM IP address [https://github.com/code-ready/crc/blob/0d76300c1a618598c209bab32a8deb4ca6c2d8c6/pkg/drivers/vfkit/network_darwin.go#L54-L59] -## [vz](https://pkg.go.dev/github.com/Code-Hex/vz/v2) API +## [vz](https://pkg.go.dev/github.com/Code-Hex/vz/v3) APIs ``` func vz.CreateDiskImage(pathname string, size int64) error func vz.VirtualMachineConfigurationMaximumAllowedCPUCount() uint @@ -37,4 +37,3 @@ This document contains a non-exhaustive list of API which are not used/supported type VirtualMachineConfiguration func (v *VirtualMachineConfiguration) vz.SetMemoryBalloonDevicesVirtualMachineConfiguration(cs []MemoryBalloonDeviceConfiguration) ``` - diff --git a/doc/quickstart.md b/doc/quickstart.md index 3d010142..288b5a9a 100644 --- a/doc/quickstart.md +++ b/doc/quickstart.md @@ -15,9 +15,9 @@ UEFI boot and graphical user interface support are only available on macOS 13 or You can get vfkit either by downloading it from [its release page](https://github.com/crc-org/vfkit/releases), or get it from [brew](https://brew.sh/): ``` # Only the first time -$ brew tap cfergeau/crc +brew tap cfergeau/crc -$ brew install vfkit +brew install vfkit ``` @@ -32,14 +32,14 @@ VirtualBox images cannot be used by vfkit. For example, Fedora images can be downloaded with: ``` # For Apple silicon Macs -$ curl -L -O https://download.fedoraproject.org/pub/fedora/linux/releases/38/Cloud/aarch64/images/Fedora-Cloud-Base-38-1.6.aarch64.raw.xz -$ xz -d ./Fedora-Cloud-Base-38-1.6.aarch64.raw.xz -$ mv Fedora-Cloud-Base-38-1.6.aarch64.raw vfkit-test-image.raw +curl -L -O https://download.fedoraproject.org/pub/fedora/linux/releases/38/Cloud/aarch64/images/Fedora-Cloud-Base-38-1.6.aarch64.raw.xz +xz -d ./Fedora-Cloud-Base-38-1.6.aarch64.raw.xz +mv Fedora-Cloud-Base-38-1.6.aarch64.raw vfkit-test-image.raw # For Intel Macs -$ curl -L https://download.fedoraproject.org/pub/fedora/linux/releases/38/Cloud/x86_64/images/Fedora-Cloud-Base-38-1.6.x86_64.raw.xz -$ xz -d ./Fedora-Cloud-Base-38-1.6.x86_64.raw.xz -$ mv Fedora-Cloud-Base-38-1.6.x86_64.raw vfkit-test-image.raw +curl -L https://download.fedoraproject.org/pub/fedora/linux/releases/38/Cloud/x86_64/images/Fedora-Cloud-Base-38-1.6.x86_64.raw.xz +xz -d ./Fedora-Cloud-Base-38-1.6.x86_64.raw.xz +mv Fedora-Cloud-Base-38-1.6.x86_64.raw vfkit-test-image.raw ``` @@ -49,7 +49,7 @@ $ mv Fedora-Cloud-Base-38-1.6.x86_64.raw vfkit-test-image.raw Now that we have a disk image, we can start a virtual machine with 2 virtual CPUs and 2GiB of RAM: ``` -$ vfkit \ +vfkit \ --cpus 2 --memory 2048 \ --bootloader efi,variable-store=efi-variable-store,create \ --device virtio-blk,path=vfkit-test-image.raw diff --git a/doc/usage.md b/doc/usage.md index 38887f96..a867dc16 100644 --- a/doc/usage.md +++ b/doc/usage.md @@ -15,9 +15,9 @@ Set the log-level for VFKit. Supported values are `debug`, `info`, and `error`. - `--restful-URI` -The URI (address) of the restful service. The default is `tcp://localhost:8081`. Valid schemes are +The URI (address) of the RESTful service. The default is `tcp://localhost:8081`. Valid schemes are `tcp`, `none`, or `unix`. In the case of unix, the "host" portion would be a path to where the unix domain -socket will be stored. A scheme of `none` disables the restful service. +socket will be stored. A scheme of `none` disables the RESTful service. ### Virtual Machine Resources @@ -132,7 +132,7 @@ However, APFS, the default macOS filesystem has support for sparse files and cop A sparse raw image can be created/expanded using the `truncate` command or using [`truncate(2)`](https://manpagez.com/man/2/truncate/). -For example, an empty 1GiB disk can be created with `truncate --size 1G +For example, an empty 1GiB disk can be created with `truncate -s 1G vfkit.img`. Such an image will only use disk space when content is written to it. It initially only uses a few bytes of actual disk space even if it's size is 1G. @@ -385,11 +385,11 @@ None `--device virtio-input,pointing` -## Restful Service +## RESTful Service ### Get VM state -Used to obtain the state of the virtual machine that is being run by VFKit. +Used to obtain the state of the virtual machine that is being run by vfkit. GET `/vm/state` Response: { "state": string, "canStart": bool, "canPause": bool, "canResume": bool, "canStop": bool, "canHardStop": bool } @@ -427,7 +427,7 @@ In order to tell vfkit that you want to start a graphical application window, yo ### Usage -Proper use of this flag may look similar to the following section of a command: +Proper use of this flag may look similar to the following section of a command: ```bash --device virtio-input,keyboard --device virtio-input,pointing --device virtio-gpu,width=1920,height=1080 --gui ``` diff --git a/pkg/cmdline/cmdline.go b/pkg/cmdline/cmdline.go index d912240b..20bcea16 100644 --- a/pkg/cmdline/cmdline.go +++ b/pkg/cmdline/cmdline.go @@ -28,8 +28,8 @@ type Options struct { const DefaultRestfulURI = "none://" func AddFlags(cmd *cobra.Command, opts *Options) { - cmd.Flags().StringVarP(&opts.VmlinuzPath, "kernel", "k", "", "path to the virtual machine linux kernel") - cmd.Flags().StringVarP(&opts.KernelCmdline, "kernel-cmdline", "C", "", "linux kernel command line") + cmd.Flags().StringVarP(&opts.VmlinuzPath, "kernel", "k", "", "path to the virtual machine Linux kernel") + cmd.Flags().StringVarP(&opts.KernelCmdline, "kernel-cmdline", "C", "", "Linux kernel command line") cmd.Flags().StringVarP(&opts.InitrdPath, "initrd", "i", "", "path to the virtual machine initrd") cmd.Flags().VarP(&opts.Bootloader, "bootloader", "b", "bootloader configuration") @@ -48,6 +48,6 @@ func AddFlags(cmd *cobra.Command, opts *Options) { cmd.Flags().StringArrayVarP(&opts.Devices, "device", "d", []string{}, "devices") cmd.Flags().StringVar(&opts.LogLevel, "log-level", "", "set log level") - cmd.Flags().StringVar(&opts.RestfulURI, "restful-uri", DefaultRestfulURI, "URI address for RestFul services") + cmd.Flags().StringVar(&opts.RestfulURI, "restful-uri", DefaultRestfulURI, "URI address for RESTful services") } diff --git a/pkg/config/bootloader.go b/pkg/config/bootloader.go index 67510881..ecf02229 100644 --- a/pkg/config/bootloader.go +++ b/pkg/config/bootloader.go @@ -52,7 +52,7 @@ func (bootloader *LinuxBootloader) FromOptions(options []option) error { case "initrd": bootloader.InitrdPath = option.value default: - return fmt.Errorf("unknown option for linux bootloaders: %s", option.key) + return fmt.Errorf("unknown option for Linux bootloaders: %s", option.key) } } return nil From d1744f5d81d7292434d012e6ab2cf2301c554ff5 Mon Sep 17 00:00:00 2001 From: Christophe Fergeau Date: Thu, 16 May 2024 11:04:04 +0200 Subject: [PATCH 2/2] Update doc/missing-vz-api.md Co-authored-by: William Theaker --- doc/missing-vz-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/missing-vz-api.md b/doc/missing-vz-api.md index 14faa596..26910f58 100644 --- a/doc/missing-vz-api.md +++ b/doc/missing-vz-api.md @@ -1,6 +1,6 @@ # Missing APIs -This document contains a non-exhaustive list of APIs not currently used/supported by `vfkit`, but could be useful to have. +This document is a non-exhaustive list of unimplemented APIs, which may be worth adding to `vfkit`. ## non-vz APIs