Repository files navigation

Packagego-libvirt provides a pure Go interface for interacting with libvirt.

Rather than using libvirt's C bindings, this package makes use oflibvirt's RPC interface, as documentedhere.Connections to the libvirt server may be local, or remote. RPC packets are encodedusing the XDR standard as defined byRFC 4506.

libvirt's RPC interface is quite extensive, and changes from one version to the next, sothis project uses a code generator to build the go bindings. The code generator shouldbe run whenever you want to build go-libvirt for a new version of libvirt. To do this,you'll need to set an environment variableLIBVIRT_SOURCE to the directory containingthe untarred libvirt sources, and then rungo generate ./... from the go-libvirt directory.The code generator consumessrc/remote/remote_protocol.xand produces go bindings for all the remote procedures defined there.

Pull requests are welcome!

Once you've vendored go-libvirt into your project, you'll probably want to callsome libvirt functions. There's some example code below showing how to connectto libvirt and make one such call, but once you get past the introduction you'llnext want to call some other libvirt functions. How do you find them?

Start with thelibvirt API reference.Let's say you want to gracefully shutdown a VM, and after reading through thelibvirt docs you determine that virDomainShutdown() is the function you want tocall to do that. Where's that function in go-libvirt? We transform the namesslightly when building the go bindings. There's no need for a global prefix like"vir" in Go, since all our functions are inside the package namespace, so wedrop it. That means the Go function forvirDomainShutdown() is justDomainShutdown(),and sure enough, you can find the Go functionDomainShutdown() in libvirt.gen.go,with parameters and return values equivalent to those documented in the APIreference.

Suppose you then decide you need more control over your shutdown, so you switchover tovirDomainShutdownFlags(). As its name suggests, this function takes aflag parameter which has possible values specified in an enum calledvirDomainShutdownFlagValues. Flag types like this are a little tricky for thecode generator, because the C functions just take an integer type - only thelibvirt documentation actually ties the flags to the enum types. In most casesthough we're able to generate a wrapper function with a distinct flag type,making it easier for Go tooling to suggest possible flag values while you'reworking. Checking the documentation for this function:

godoc github.com/digitalocean/go-libvirt DomainShutdownFlags

returns this:

func (l *Libvirt) DomainShutdownFlags(Dom Domain, Flags DomainShutdownFlagValues) (err error)

If you want to see the possible flag values,godoc can help again:

$ godoc github.com/digitalocean/go-libvirt DomainShutdownFlagValuestype DomainShutdownFlagValues int32    DomainShutdownFlagValues as declared in libvirt/libvirt-domain.h:1121const (    DomainShutdownDefault      DomainShutdownFlagValues = iota    DomainShutdownAcpiPowerBtn DomainShutdownFlagValues = 1    DomainShutdownGuestAgent   DomainShutdownFlagValues = 2    DomainShutdownInitctl      DomainShutdownFlagValues = 4    DomainShutdownSignal       DomainShutdownFlagValues = 8    DomainShutdownParavirt     DomainShutdownFlagValues = 16)    DomainShutdownFlagValues enumeration from libvirt/libvirt-domain.h:1121

One other suggestion: most of the code in go-libvirt is now generated, but a fewhand-written routines still exist in libvirt.go, and wrap calls to the generatedcode with slightly different parameters or return values. We suggest avoidingthese hand-written routines and calling the generated routines in libvirt.gen.goinstead. Over time these handwritten routines will be removed from go-libvirt.

The libvirt project strongly recommendsagainst talking to the RPC interfacedirectly. They consider it to be a private implementation detail with thepossibility of being entirely rearchitected in the future.

While these package are reasonably well-tested and have seen some use inside ofDigitalOcean, there may be subtle bugs which could cause the packages to actin unexpected ways. Use at your own risk!

In addition, the API is not considered stable at this time. If you would liketo include packagelibvirt in a project, we highly recommend vendoring it intoyour project.

package mainimport ("fmt""log""net""time""github.com/digitalocean/go-libvirt")funcmain() {// This dials libvirt on the local machine, but you can substitute the first// two parameters with "tcp", "<ip address>:<port>" to connect to libvirt on// a remote machine.c,err:=net.DialTimeout("unix","/var/run/libvirt/libvirt-sock",2*time.Second)iferr!=nil {log.Fatalf("failed to dial libvirt: %v",err)}l:=libvirt.New(c)iferr:=l.Connect();err!=nil {log.Fatalf("failed to connect: %v",err)}v,err:=l.Version()iferr!=nil {log.Fatalf("failed to retrieve libvirt version: %v",err)}fmt.Println("Version:",v)domains,err:=l.Domains()iferr!=nil {log.Fatalf("failed to retrieve domains: %v",err)}fmt.Println("ID\tName\t\tUUID")fmt.Printf("--------------------------------------------------------\n")for_,d:=rangedomains {fmt.Printf("%d\t%s\t%x\n",d.ID,d.Name,d.UUID)}iferr:=l.Disconnect();err!=nil {log.Fatalf("failed to disconnect: %v",err)}}

Version: 1.3.4IDNameUUID--------------------------------------------------------1Test-1dc329f87d4de47198cfd2e21c6105b012Test-2dc229f87d4de47198cfd2e21c6105b01