Qemu wrapper for kernel-related CI tasks. Supports GNU/Linux and macOS.


  • Uses upstream virtualization -- KVM in GNU/Linux and Hypervisor.framework in macOS.
  • Run files and kernel modules directly from local filesystem. No need to copy byself!
  • Run commands inside qemu virtual machine at the same way as you run in it locally.


$ go get
Generate root image

First of all we need to generate rootfs for run qemu.

Install qemu and docker
$ sudo apt install -y qemu docker

Note: qemu on macOS since v2.12 (24 April 2018) supports Hypervisor.framework.

$ brew install qemu
$ brew cask install docker
Generate image
$ cd $GOPATH/src/
$ ./
Fill configuration file
Run tests
$ go test -v


$ go get

Minimal example:

kernel := qemu.Kernel{
    Name:       "Some kernel name",
    KernelPath: "/path/to/vmlinuz",
    InitrdPath: "/path/to/initrd", // if required
q, err := qemu.NewSystem(qemu.X86_64, kernel, "/path/to/qcow2")
if err != nil {

if err = q.Start(); err != nil {
defer q.Stop()

output, err = q.Command("root", "echo Hello, World!")
if err != nil {

// output == "Hello, World!\n"

More information and list of all functions see at go documentation project, or just run locally:

$ godoc
Expand ▾ Collapse ▴




View Source
const (
	// X86x64 is the qemu-system-x86_64
	X86x64 arch = "x86_64"
	// X86x32 is the qemu-system-i386
	X86x32 = "i386"


This section is empty.


This section is empty.


type Kernel

type Kernel struct {
	Name       string
	KernelPath string
	InitrdPath string

    Kernel describe kernel parameters for qemu

    type System

    type System struct {
    	Cpus   int
    	Memory int
    	// Timeout works after Start invocation
    	Timeout         time.Duration
    	KilledByTimeout bool
    	KernelPanic bool
    	Died bool
    	Stdout, Stderr []byte
    	// contains filtered or unexported fields

      System describe qemu parameters and executed process

      func NewSystem

      func NewSystem(arch arch, kernel Kernel, drivePath string) (q *System, err error)

        NewSystem constructor

        func (System) AsyncCommand

        func (q System) AsyncCommand(user, cmd string) (err error)

          AsyncCommand executes command on qemu system but does not wait for exit

          func (System) Command

          func (q System) Command(user, cmd string) (output string, err error)

            Command executes shell commands on qemu system

            func (*System) CopyAndInsmod

            func (q *System) CopyAndInsmod(localKoPath string) (output string, err error)

              CopyAndInsmod copy kernel module to temporary file on qemu then insmod it

              func (*System) CopyAndRun

              func (q *System) CopyAndRun(user, path string) (output string, err error)

                CopyAndRun is copy local file to qemu vm then run it

                func (*System) CopyFile

                func (q *System) CopyFile(user, localPath, remotePath string) (err error)

                  CopyFile is copy file from local machine to remote through ssh/scp

                  func (*System) Debug

                  func (q *System) Debug(conn string)

                    Debug is for enable qemu debug and set hostname and port for listen

                    func (*System) GetKASLR

                    func (q *System) GetKASLR() bool

                      GetKASLR is retrieve KASLR settings

                      func (*System) GetKPTI

                      func (q *System) GetKPTI() bool

                        GetKPTI is retrieve KPTI settings

                        func (*System) GetSMAP

                        func (q *System) GetSMAP() bool

                          GetSMAP is retrieve SMAP settings

                          func (*System) GetSMEP

                          func (q *System) GetSMEP() bool

                            GetSMEP is retrieve SMEP settings

                            func (System) GetSSHCommand

                            func (q System) GetSSHCommand() (cmd string)

                              GetSSHCommand returns command for connect to qemu machine over ssh

                              func (*System) SetKASLR

                              func (q *System) SetKASLR(state bool)

                                SetKASLR is changing KASLR state through kernel boot args

                                func (*System) SetKPTI

                                func (q *System) SetKPTI(state bool)

                                  SetKPTI is changing KPTI state through kernel boot args

                                  func (*System) SetSMAP

                                  func (q *System) SetSMAP(state bool)

                                    SetSMAP is changing SMAP state through kernel boot args

                                    func (*System) SetSMEP

                                    func (q *System) SetSMEP(state bool)

                                      SetSMEP is changing SMEP state through kernel boot args

                                      func (*System) Start

                                      func (q *System) Start() (err error)

                                        Start qemu process

                                        func (*System) Stop

                                        func (q *System) Stop()

                                          Stop qemu process