go-qcow2lib

Go qcow2 file library introduction

This package provides a Golang-implemented qcow2 file handling library, which is largely ported from the qemu but it doesn't implement all the functions of qemu, just a set of core functions of it.

The purpose of implementing this library in Golang is to provide a way for applications to use the qcow2 format storage, such as providing qcow2-based backend block storage for containers in cloud-native environments.

The following features of qemu are supported:

• General qcow2 file operation (e.g. create, open, close, write, read)
• Subcluster.
• Backing file chain. (external snapshot).
• L2 and refcount block caches.
• Block discards
• External data file

And following features of qemu will not be supported:

• Internal snapshot (suggest using external snapshot for production)
• Compression
• Lazy refcounts
• Header extensions.
• Bitmaps extension.

And following features are not supported yet but have been planned

• Data encryption (LUKS only)
• Preallocation

It doesn't support configurable qcow2 format-related values like that the qemu-img utility does (e.g. cluster size, refcount entry size, etc.), instead, it always uses qcow2-format values that are equal to the default values of qcow2 file which generated by the qemu-img utility, as follows:

• A fixed cluster size value of 64 KiB, a fixed sub-cluster size of 2 KiB if the subcluster feature enabled
• A fixed qcow2 version of 3.
• A fixed refcount_bits of 16 or refcount_order of 4.
• The size of a qcow2 file is limited to 4 TiB.

The l2 cache and refcount cache of the qcow2 library is always automatically allocated large enough memory according to the virtual size of the opened qcow2 file, however, you can specify the size of l2 cache for a newly opened qcow2 file, and the size of the refcount cache is allocated as the half of the l2 cache. The size of the cache can be obtained by the below calculation:

• 512 MiB virtual size of qcow2 file needs 64 KiB l2 cache.
• 1 GiB virtual size of qcow2 file needs 128 KiB l2 cache.
• 8 GiB virtual size of qcow2 file needs 1 MiB l2 cache.
• 1 TiB virtual size of qcow2 file needs 128 MiB l2 cache.
• ......

Quick Start

See Examples

Qcow2 Utility

make 
bin/qcow2util create <-f filename> <-s filesize> [-b backingfile] [-d datafile] [--enable-subcluster]
bin/qcow2util info <-f filename> [--detail] [--pretty] 
bin/qcow2util dd <-i inputfile> [-f inputformat] <-o outputfile> <-O outputformat> [--l2-cache-size=size]

License

MIT License

Copyright (c) Yunpeng Deng(dypflying)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Report Issues

Please report bugs to GitHub Issue Tracker

Contact Author

• Author: Yunpeng Deng (dypflying)
• Mailto: dypflying@sina.com

Either English or Chinese is welcome.