go-libvirt

The go-libvirt package provides a pure Go interface for interacting with libvirt via its RPC interface (using XDR encoding).

Mapping libvirt C functions to Go

Functions in the Go package are mapped from the libvirt C API by removing the vir prefix. For example:

• virDomainShutdown() becomes DomainShutdown()
• virDomainShutdownFlags() becomes DomainShutdownFlags()

Best Practices

• Use generated code: Most of the library is generated. While libvirt.go contains some hand-written routines, it is recommended to call the generated routines in libvirt.gen.go directly, as the hand-written ones may be removed in future versions.
• Vendoring: Because the API is not considered stable, it is highly recommended to vendor go-libvirt into your project.
• Error Handling: Always check for errors returned by connection and API calls, as the library may return 'unimplemented' errors if the generated code does not match your local libvirt version.

When subscribing to domain events, the following message structures are used to communicate lifecycle and status changes:

Lifecycle & Status Messages

• Lifecycle Event: DomainEventLifecycleMsg contains the Dom (Domain), Event (int32), and Detail (int32).
• Reboot: DomainEventRebootMsg contains the Dom (Domain).
• RTC Change: DomainEventRtcChangeMsg contains the Dom (Domain) and Offset (int64).
• Watchdog: DomainEventWatchdogMsg contains the Dom (Domain) and Action (int32).
• IO Error: DomainEventIOErrorMsg contains Dom (Domain), SrcPath (string), DevAlias (string), and Action (int32). DomainEventIOErrorReasonMsg adds a Reason (string).
• Graphics: DomainEventGraphicsMsg contains Dom (Domain), Phase (int32), Local and Remote (DomainEventGraphicsAddress), AuthScheme (string), and Subject ([]DomainEventGraphicsIdentity).
• Block Job: DomainEventBlockJobMsg contains Dom (Domain), Path (string), Type (int32), and Status (int32).
• Disk Change: DomainEventDiskChangeMsg contains Dom (Domain), OldSrcPath (OptString), NewSrcPath (OptString), DevAlias (string), and Reason (int32).
• Tray Change: DomainEventTrayChangeMsg contains Dom (Domain), DevAlias (string), and Reason (int32).
• PM Events: DomainEventPmwakeupMsg (contains Dom), DomainEventPmsuspendMsg (contains Dom), and DomainEventPmsuspendDiskMsg (contains Dom).
• Balloon Change: DomainEventBalloonChangeMsg contains Dom (Domain) and Actual (uint64).

You can connect to a local or remote libvirt instance using a URI. The following example demonstrates connecting to the local QEMU system and listing active/inactive domains.

package main

import (
	"fmt"
	"log"
	"net/url"

	"github.com/digitalocean/go-libvirt"
)

func main() {
	uri, _ := url.Parse(string(libvirt.QEMUSystem))
	l, err := libvirt.ConnectToURI(uri)
	if err != nil {
		log.Fatalf("failed to connect: %v", err)
	}

	v, err := l.ConnectGetLibVersion()
	if err != nil {
		log.Fatalf("failed to retrieve libvirt version: %v", err)
	}
	fmt.Println("Version:", v)

	flags := libvirt.ConnectListDomainsActive | libvirt.ConnectListDomainsInactive
	domains, _, err := l.ConnectListAllDomains(1, flags)
	if err != nil {
		log.Fatalf("failed to retrieve domains: %v", err)
	}

	fmt.Println("ID\tName\t\tUUID")
	fmt.Printf("--------------------------------------------------------\n")
	for _, d := range domains {
		fmt.Printf("%d\t%s\t%x\n", d.ID, d.Name, d.UUID)
	}

	if err = l.Disconnect(); err != nil {
		log.Fatalf("failed to disconnect: %v", err)
	}
}

To connect to a remote libvirt instance using TLS, use libvirt.NewWithDialer with a TLS dialer from the github.com/digitalocean/go-libvirt/socket/dialers package.

Note: To connect to a remote machine, you must have the CA, client certificate, and private key (typically located in ~/.pki/libvirt/ or /etc/pki/libvirt/).

package main

        import (
        	"crypto/tls"
        	"crypto/x509"

        	"fmt"
        	"io/ioutil"
        	"log"

        	"github.com/digitalocean/go-libvirt"
        	"github.com/digitalocean/go-libvirt/socket/dialers"
        )

func main() {
        // This dials libvirt on the local machine
        // It connects to libvirt via TLS over TCP
        // To connect to a remote machine, you need to have the ca/cert/key of it.
        // The private key is at ~/.pki/libvirt/clientkey.pem
        // or /etc/pki/libvirt/private/clientkey.pem
        // The Client Cert is at ~/.pki/libvirt/clientcert.pem
        // or /etc/pki/libvirt/clientcert.pem
        // The CA Cert is at ~/.pki/libvirt/cacert.pem
        // or /etc/pki/CA/cacert.pem

        // Use host name or IP which is valid in certificate
        addr := "10.10.10.10"

        l := libvirt.NewWithDialer(dialers.NewTLS(addr))
        if err := l.Connect(); err != nil {
        	log.Fatalf("failed to connect: %v", err)
        }

        v, err := l.Version()
        if err != nil {
        	log.Fatalf("failed to retrieve libvirt version: %v", err)
        }
        fmt.Println("Version:", v)

        // Return both running and stopped VMs
        flags := libvirt.ConnectListDomainsActive | libvirt.ConnectListDomainsInactive
        domains, _, err := l.ConnectListAllDomains(1, flags)
        if err != nil {
        	log.Fatalf("failed to retrieve domains: %v", err)
        }

        fmt.Println("ID\tName\t\tUUID")
        fmt.Println("--------------------------------------------------------")
        for _, d := range domains {
        	fmt.Printf("%d\t%s\t%x\n", d.ID, d.Name, d.UUID)
        }

        if err := l.Disconnect(); err != nil {
        	log.Fatalf("failed to disconnect: %v", err)
        }
}

Use xdr.Unmarshal to decode XDR-encoded data into a Go struct. Version 2 of the library accepts an io.Reader (such as a bytes.Reader, a file, or a network connection) and a pointer to the target struct. It returns the number of bytes read and any error encountered.

package main

import (
	"bytes"
    "fmt"

    "github.com/davecgh/go-xdr/xdr2"
)

func main() {
	// Hypothetical image header format.
	type ImageHeader struct {
		Signature   [3]byte
		Version     uint32
		IsGrayscale bool
		NumSections uint32
	}

	// XDR encoded data.
	encodedData := []byte{
		0xAB, 0xCD, 0xEF, 0x00, // Signature
		0x00, 0x00, 0x00, 0x02, // Version
		0x00, 0x00, 0x00, 0x01, // IsGrayscale
		0x00, 0x00, 0x00, 0x0A, // NumSections
	}

	// Declare a variable to provide Unmarshal with a concrete type and instance
	// to decode into.
	var h ImageHeader
	bytesRead, err := xdr.Unmarshal(bytes.NewReader(encodedData), &h)
	if err != nil {
		fmt.Println(err)
		return
	}
  
	fmt.Println("bytes read:", bytesRead)
	fmt.Printf("h: %+v", h)
}

Use xdr.Marshal to encode a Go struct into the XDR data representation. Version 2 of the library accepts an io.Writer (such as a bytes.Buffer, a file, or a network connection) and a pointer to the data to be encoded. It returns the number of bytes written and any error encountered.

package main

import (
	"bytes"
    "fmt"

    "github.com/davecgh/go-xdr/xdr2"
)

func main() {
	// Hypothetical image header format.
	type ImageHeader struct {
		Signature   [3]byte
		Version     uint32
		IsGrayscale bool
		NumSections uint32
	}

	// Sample image header data.
	h := ImageHeader{[3]byte{0xAB, 0xCD, 0xEF}, 2, true, 10}

	// Use marshal to automatically determine the appropriate underlying XDR
	// types and encode.
	var w bytes.Buffer
	bytesWritten, err := xdr.Marshal(&w, &h)
	if err != nil {
		fmt.Println(err)
		return
	}

	encodedData := w.Bytes()
	fmt.Println("bytes written:", bytesWritten)
	fmt.Println("encoded data:", encodedData)
}