github.com/libvirt/libvirt-go
Package libvirt provides a Go binding to the libvirt C library Through conditional compilation it supports libvirt versions 1.2.0 onwards. This is done automatically, with no requirement to use magic Go build tags. If an API was not available in the particular version of libvirt this package was built against, an error will be returned with a code of ERR_NO_SUPPORT. This is the same code seen if using a new libvirt library to talk to an old libvirtd lacking the API, or if a hypervisor does not support a given feature, so an application can easily handle all scenarios together. The Go binding is a fairly direct mapping of the underling C API which seeks to maximise the use of the Go type system to allow strong compiler type checking. The following rules describe how APIs/constants are mapped from C to Go For structs, the 'vir' prefix and 'Ptr' suffix are removed from the name. e.g. virConnectPtr in C becomes 'Connect' in Go. For structs which are reference counted at the C level, it is neccessary to explicitly release the reference at the Go level. e.g. if a Go method returns a '* Domain' struct, it is neccessary to call 'Free' on this when no longer required. The use of 'defer' is recommended for this purpose If multiple goroutines are using the same libvirt object struct, it may not be possible to determine which goroutine should call 'Free'. In such scenarios each new goroutine should call 'Ref' to obtain a private reference on the underlying C struct. All goroutines can call 'Free' unconditionally with the final one causing the release of the C object. For methods, the 'vir' prefix and object name prefix are remove from the name. The C functions become methods with an object receiver. e.g. 'virDomainScreenshot' in C becomes 'Screenshot' with a 'Domain *' receiver. For methods which accept a 'unsigned int flags' parameter in the C level, the corresponding Go parameter will be a named type corresponding to the C enum that defines the valid flags. For example, the ListAllDomains method takes a 'flags ConnectListAllDomainsFlags' parameter. If there are not currently any flags defined for a method in the C API, then the Go method parameter will be declared as a "flags uint32". Callers should always pass the literal integer value 0 for such parameters, without forcing any specific type. This will allow compatibility with future updates to the libvirt-go binding which may replace the 'uint32' type with a enum type at a later date. For enums, the VIR_ prefix is removed from the name. The enums get a dedicated type defined in Go. e.g. the VIR_NODE_SUSPEND_TARGET_MEM enum constant in C, becomes NODE_SUSPEND_TARGET_MEM with a type of NodeSuspendTarget. Methods accepting or returning virTypedParameter arrays in C will map the parameters into a Go struct. The struct will contain two fields for each possible parameter. One boolean field with a suffix of 'Set' indicates whether the parameter has a value set, and the other custom typed field provides the parameter value. This makes it possible to distinguish a parameter with a default value of '0' from a parameter which is 0 because it isn't supported by the hypervisor. If the C API defines additional typed parameters, then the corresponding Go struct will be extended to have further fields. e.g. the GetMemoryStats method in Go (which is backed by virNodeGetMemoryStats in C) will return a NodeMemoryStats struct containing the typed parameter values. Every method that can fail will include an 'error' object as the last return value. This will be an instance of the Error struct if an error occurred. To check for specific libvirt error codes, it is neccessary to cast the error. To connect to libvirt
Readme
.. image:: https://travis-ci.org/libvirt/libvirt-go.svg?branch=master :target: https://travis-ci.org/libvirt/libvirt-go :alt: Build Status .. image:: https://img.shields.io/static/v1?label=godev&message=reference&color=00add8 :target: https://pkg.go.dev/libvirt.org/libvirt-go :alt: API Documentation
Go bindings for libvirt.
Make sure to have libvirt-dev package (or the development files
otherwise somewhere in your include path)
The libvirt go package provides API coverage for libvirt versions from 1.2.0 onwards, through conditional compilation of newer APIs.
By default the binding will support APIs in libvirt.so, libvirt-qemu.so and libvirt-lxc.so. Coverage for the latter two libraries can be dropped from the build using build tags 'without_qemu' or 'without_lxc' respectively.
The Go API is considered to be production ready and aims to be kept stable across future versions. Note, however, that the following changes may apply to future versions:
Existing structs can be augmented with new fields, but no existing fields will be changed / removed. New fields are needed when libvirt defines new typed parameters for various methods
Any method with an 'flags uint32' parameter will have its parameter type changed to a specific typedef, if & when the libvirt API defines constants for the flags. To avoid breakage, always pass a literal '0' to any 'flags uint32' parameter, since this will auto-cast to any future typedef that is introduced.
API documentation for the bindings <https://pkg.go.dev/libvirt.org/libvirt-go>_API documentation for libvirt <https://libvirt.org/html/index.html>_The libvirt project aims to add support for new APIs to libvirt-go as soon as they are added to the main libvirt C library. If you are submitting changes to the libvirt C library API, please submit a libvirt-go change at the same time. Bug fixes and other improvements to the libvirt-go library are welcome at any time.
For more information, see the CONTRIBUTING <CONTRIBUTING.rst>_
file.
The core API unit tests are all written to use the built-in test driver (test:///default), so they have no interaction with the host OS environment.
Coverage of libvirt C library APIs / constants is verified using automated tests. These can be run by passing the 'api' build tag. eg go test -tags api
For areas where the test driver lacks functionality, it is possible to use the QEMU or LXC drivers to exercise code. Such tests must be part of the 'integration_test.go' file though, which is only run when passing the 'integration' build tag. eg go test -tags integration
In order to run the unit tests, libvirtd should be configured to allow your user account read-write access with no passwords. This can be easily done using polkit config files
::
[Passwordless libvirt access] Identity=unix-group:berrange Action=org.libvirt.unix.manage ResultAny=yes ResultInactive=yes ResultActive=yes EOF
(Replace 'berrange' with your UNIX user name).
Two of the integration tests also requires that libvirtd is listening for TCP connections on localhost, with sasl auth This can be setup by editing /etc/libvirt/libvirtd.conf to set
::
listen_tls=0 listen_tcp=1 auth_tcp=sasl listen_addr="127.0.0.1"
and then start libvirtd with the --listen flag (this can be set in /etc/sysconfig/libvirtd to make it persistent).
sasl authentication must be configured_ to use either digest-md5 or
scram-sha-1, and the needed sasl modules must be installed on the system.
.. _configured: https://libvirt.org/auth.html#ACL_server_sasl
Then create a sasl user
::
$ saslpasswd2 -a libvirt user
and enter "pass" as the password.
Alternatively a Vagrantfile, requiring use of virtualbox,
is included to run the integration tests:
cd ./vagrantvagrant up to provision the virtual machinevagrant ssh to login to the virtual machineOnce inside, sudo su - and go test -tags integration libvirt.
FAQs
Package libvirt provides a Go binding to the libvirt C library Through conditional compilation it supports libvirt versions 1.2.0 onwards. This is done automatically, with no requirement to use magic Go build tags. If an API was not available in the particular version of libvirt this package was built against, an error will be returned with a code of ERR_NO_SUPPORT. This is the same code seen if using a new libvirt library to talk to an old libvirtd lacking the API, or if a hypervisor does not support a given feature, so an application can easily handle all scenarios together. The Go binding is a fairly direct mapping of the underling C API which seeks to maximise the use of the Go type system to allow strong compiler type checking. The following rules describe how APIs/constants are mapped from C to Go For structs, the 'vir' prefix and 'Ptr' suffix are removed from the name. e.g. virConnectPtr in C becomes 'Connect' in Go. For structs which are reference counted at the C level, it is neccessary to explicitly release the reference at the Go level. e.g. if a Go method returns a '* Domain' struct, it is neccessary to call 'Free' on this when no longer required. The use of 'defer' is recommended for this purpose If multiple goroutines are using the same libvirt object struct, it may not be possible to determine which goroutine should call 'Free'. In such scenarios each new goroutine should call 'Ref' to obtain a private reference on the underlying C struct. All goroutines can call 'Free' unconditionally with the final one causing the release of the C object. For methods, the 'vir' prefix and object name prefix are remove from the name. The C functions become methods with an object receiver. e.g. 'virDomainScreenshot' in C becomes 'Screenshot' with a 'Domain *' receiver. For methods which accept a 'unsigned int flags' parameter in the C level, the corresponding Go parameter will be a named type corresponding to the C enum that defines the valid flags. For example, the ListAllDomains method takes a 'flags ConnectListAllDomainsFlags' parameter. If there are not currently any flags defined for a method in the C API, then the Go method parameter will be declared as a "flags uint32". Callers should always pass the literal integer value 0 for such parameters, without forcing any specific type. This will allow compatibility with future updates to the libvirt-go binding which may replace the 'uint32' type with a enum type at a later date. For enums, the VIR_ prefix is removed from the name. The enums get a dedicated type defined in Go. e.g. the VIR_NODE_SUSPEND_TARGET_MEM enum constant in C, becomes NODE_SUSPEND_TARGET_MEM with a type of NodeSuspendTarget. Methods accepting or returning virTypedParameter arrays in C will map the parameters into a Go struct. The struct will contain two fields for each possible parameter. One boolean field with a suffix of 'Set' indicates whether the parameter has a value set, and the other custom typed field provides the parameter value. This makes it possible to distinguish a parameter with a default value of '0' from a parameter which is 0 because it isn't supported by the hypervisor. If the C API defines additional typed parameters, then the corresponding Go struct will be extended to have further fields. e.g. the GetMemoryStats method in Go (which is backed by virNodeGetMemoryStats in C) will return a NodeMemoryStats struct containing the typed parameter values. Every method that can fail will include an 'error' object as the last return value. This will be an instance of the Error struct if an error occurred. To check for specific libvirt error codes, it is neccessary to cast the error. To connect to libvirt
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Cyber extortion in the US and Canada hit record levels in 2023, with ransomware attacks surging and median ransom demands skyrocketing, though fewer companies are choosing to pay ransoms.
Security News
Ecma TC39 is meeting this week and has moved key ECMAScript proposals forward, advancing Deferred Import Evaluation, Error.isError(), RegExp Escaping, and Promise.try to the next stages.
Security News
Researchers have demonstrated that teams of LLM agents can exploit zero-day vulnerabilities with a 53% success rate, and the costs of using AI to do so are rapidly becoming more affordable than hiring a human penetration tester.