vm

README

About

vm is a command line utility that provides a high-level interface to create and manage virtual machines through libvirt.

It supports creation and deletion of domains and snapshots, connecting to serial and SSH terminals, downloading and converting templates from vagrantup.com and builder.libguestfs.org, and importing locally downloading images.

Installation

go get -u github.com/subpop/vm/cmd/vm

Distribution

vm includes a Makefile to aid distributions in packaging. The default target will build vm along with shell completion data and a man page. The Makefile includes an install target to install the binary and data into distribution-appropriate locations. To override the installation directory (commonly referred to as the DESTDIR), set the DESTDIR variable when running the install target:

[link@localhost vm]$ make
go build ./cmd/vm
go run ./cmd/vm --generate-fish-completion > vm.fish
go run ./cmd/vm --generate-bash-completion > vm.bash
go run ./cmd/vm --generate-man-page > vm.1
gzip -k vm.1
[link@localhost vm]$ make DESTDIR=_inst install
install -D -m755 -t _inst//usr/local/bin vm
install -D -m644 -t _inst//usr/local/share/man/man1 vm.1.gz
install -D -m644 -t _inst//usr/local/share/fish/completions vm.fish
install -d _inst//usr/local/share/bash-completion/completions
install -m644 -T vm.bash _inst//usr/local/share/bash-completion/completions/vm
[link@localhost vm]$

Usage

Download a base image:

vm image get https://dl.fedoraproject.org/pub/fedora/linux/releases/31/Cloud/x86_64/images/Fedora-Cloud-Base-31-1.9.x86_64.qcow2

Download and convert a Vagrant ".box":

vm image get https://dl.fedoraproject.org/pub/fedora/linux/releases/31/Cloud/x86_64/images/Fedora-Cloud-Base-Vagrant-31-1.9.x86_64.vagrant-libvirt.box

Create a domain backed by that image:

vm create Fedora-Cloud-Base-31-1.9.x86_64 --name my-f31

Create a domain without defining it:

vm create Fedora-Cloud-Base-31-1.9.x86_64 --transient

List active domains:

vm list

Start a created domain:

vm up my-f31

Connect to an existing domain over SSH:

vm connect -m ssh -u vagrant my-f31 -i ~/.ssh/cloud_user_rsa

Connect to an existing domain over VirtIO PTY:

vm connect -m console my-f31

Take a snapshot:

vm snapshot create my-f31 --name fresh_install

Revert to snapshot:

vm snapshot revert my-f31 --snapshot fresh_install

Documentation

Index

• Variables
• func Connect(name string, mode string, user, identity string) error
• func Create(name, image string, disks []string, options CreateOptions, config CreateConfig) error
• func Destroy(name string, force bool) error
• func Down(name string, force bool, graceful bool) error
• func ImageGet(rawurl string, newName string, quiet bool) error
• func ImageList() error
• func ImageRemove(name string, force bool) error
• func Inspect(name, outputformat string) error
• func List(active, inactive bool) error
• func LogErrorAndExit(err error)
• func Restart(name string, force bool, graceful bool) error
• func SnapshotCreate(domainName, snapshotName string) error
• func SnapshotList(name string) error
• func SnapshotRemove(domainName, snapshotName string) error
• func SnapshotRevert(domainName, snapshotName string) error
• func TemplateGet(name, arch string, quiet bool) error
• func TemplateInfo(name, arch string) error
• func TemplateList(sortBy string) error
• func TemplateSync() error
• func Up(name string, connectAfterUp bool) error
• type CreateConfig
• type CreateOptions
• type MissingPositionalArgErr
  • func (e MissingPositionalArgErr) Error() string

Variables

var ErrDomainNameRequired = MissingPositionalArgErr{
	// contains filtered or unexported fields
}

ErrDomainNameRequired represents a missing domain name argument.

var ErrImageNameRequired = MissingPositionalArgErr{
	// contains filtered or unexported fields
}

ErrImageNameRequired represents a missing image name argument.

var ErrTemplateNameRequired = MissingPositionalArgErr{
	// contains filtered or unexported fields
}

ErrTemplateNameRequired represents a missing template name argument.

var ErrURLOrPathRequired = MissingPositionalArgErr{
	// contains filtered or unexported fields
}

ErrURLOrPathRequired represents a missing URL or path argument.

Functions

func Connect

func Connect(name string, mode string, user, identity string) error

Connect opens a connection to a domain by name. The mode argument determines the connection mode: either "ssh" or "console".

func Create

func Create(name, image string, disks []string, options CreateOptions, config CreateConfig) error

Create defines a new domain using name and creating a disk image backed by image. If connect is true, a console is attached to the newly created domain. If transient is true, the domain is destroy upon shutdown.

func Destroy

func Destroy(name string, force bool) error

Destroy stops and undefines a domain by name. If force is true, the domain is destroyed without prompting for confirmation.

func Down

func Down(name string, force bool, graceful bool) error

Down looks up an active domain by name and stops it. If force is true, the domain is stopped without prompting for confirmation. If graceful is true, the domain is shutdown gracefully.

func ImageGet

func ImageGet(rawurl string, newName string, quiet bool) error

ImageGet downloads rawurl and prepares it for use as a backing disk image. If newName is not empty, the image is renamed to newName. If quiet is true, no progress is printed to stdout.

func ImageList

func ImageList() error

ImageList prints a list of downloaded base images.

func ImageRemove

func ImageRemove(name string, force bool) error

ImageRemove deletes image name from image storage directory. If force is true, the image is deleted without prompting for confirmation.

func Inspect

func Inspect(name, outputformat string) error

Inspect prints detailed information about the given domain.

func List

func List(active, inactive bool) error

List prints a list of known domains. If active is true, active domains are included in the list. If inactive is true, inactive domains are included in the list.

func LogErrorAndExit

func LogErrorAndExit(err error)

LogErrorAndExit logs err and exits with a non-zero exit code.

func Restart

func Restart(name string, force bool, graceful bool) error

Restart looks up a domain by name and restarts it. If force is true, the domain is restarted without prompting for user confirmation first. If graceful is false, the dom is reset forcibly rather than being sent a restart signal.

func SnapshotCreate

func SnapshotCreate(domainName, snapshotName string) error

SnapshotCreate saves a new snapshot for the given domain.

func SnapshotList

func SnapshotList(name string) error

SnapshotList prints a table of snapshots for the given domain.

func SnapshotRemove

func SnapshotRemove(domainName, snapshotName string) error

SnapshotRemove deletes the given snapshot for the given domain.

func SnapshotRevert

func SnapshotRevert(domainName, snapshotName string) error

SnapshotRevert discards the current domain state, reverting it to snapshotName.

func TemplateGet

func TemplateGet(name, arch string, quiet bool) error

TemplateGet downloads and prepares a disk template for use as a backing disk image. If quiet is true, no progress is printed to stdout.

func TemplateInfo

func TemplateInfo(name, arch string) error

TemplateInfo prints information about template with name and arch.

func TemplateList

func TemplateList(sortBy string) error

TemplateList prints a list of available templates.

func TemplateSync

func TemplateSync() error

TemplateSync downloads the latest index and caches it.

func Up

func Up(name string, connectAfterUp bool) error

Up looks up a defined domain by name and starts it.

Types

type CreateConfig

type CreateConfig struct {
	// Use UEFI boot instead of BIOS
	UEFI bool
}

CreateConfig store customization options for modifying the domain parameters during creation.

type CreateOptions

type CreateOptions struct {
	// Automatically connect to the domain's first serial port after creation.
	ConnectAfterCreate bool

	// Remove the create domain after it is shutdown.
	IsTransient bool

	// Create a snapshot immediately after creating the domain, before it is
	// started.
	CreateInitialSnapshot bool
}

CreateOptions store various options for modifying the domain creation behavior.

type MissingPositionalArgErr

type MissingPositionalArgErr struct {
	// contains filtered or unexported fields
}

A MissingPositionalArgErr occurs when a command is invoked without a required positional argument.

func (MissingPositionalArgErr) Error

func (e MissingPositionalArgErr) Error() string