{"id":6685,"date":"2018-04-24T08:11:09","date_gmt":"2018-04-24T06:11:09","guid":{"rendered":"https:\/\/anexia.com\/stagingblog\/?p=6685"},"modified":"2022-04-21T13:31:05","modified_gmt":"2022-04-21T11:31:05","slug":"filesystem-quota-management-in-go","status":"publish","type":"post","link":"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/","title":{"rendered":"Filesystem quota management in Go"},"content":{"rendered":"

Filesystem quotas are a rather simple concept. Instead of allowing every user to use all of the available space on a filesystem (or drive, to be less technical) each user is confined to limits – so called quotas. These quotas determine how much space an individual user or group may use.<\/p>\n

Currently Go does not include support for controlling filesystem quotas in its otherwise vast standard library. Unfortunately, no third-party libraries which would add this functionality exist either. One of our current project at the Anexia R&D department<\/a> has to control quotas from within Go, therefore, we decided to come up with a solution of our own: a Go-native implementation.<\/p>\n

This gives me the opportunity to demonstrate how Go interacts with the underlying operating system at the deepest layers, namely at the syscall<\/em> level. We will go over the steps again taken during the development of our solution. This will explain how the neccessary research was conducted and how we developed our quota library.<\/p>\n

Kernel interface<\/h2>\n

In Linux libc<\/em> exposes support for controlling filesystem quotas via its quotactl<\/em> function. musl-libc<\/em> shows that quotactl can be a thin wrapper around the underlying syscall of the same name:<\/p>\n

int quotactl(int cmd, const char *special, int id, char *addr)\r\n{\r\n  return syscall(SYS_quotactl, cmd, special, id, addr);\r\n}<\/pre>\n
This function, along with a few C preprocessor macros which are defined in musl<\/em>’s include\/sys\/quota.h<\/em>, provides full filesystem quota support. As we can see, we only required a thin wrapper like the one present in musl-libc<\/em> to make Go aware of filesystem quotas – this is the point where we start out adventure into implementing this functionality on top of Go.<\/p>\n
Preparing a testbed<\/h2>\n
Before being able to conduct any tests, we need a testbed. We chose to create a new ext4 filesystem in a file, activate quotas and loop-mount this file:<\/p>\n
$ truncate -s 1G \/tmp\/test.ext4\r\n$ \/sbin\/mkfs.ext4 \/tmp\/test.ext4\r\n$ sudo mkdir -p \/mnt\/quota_test\r\n$ sudo mount -o usrjquota=aquota.user,grpjquota=aquota.group,jqfmt=vfsv1 \/tmp\/test.ext4 \/mnt\/quota_test\r\n$ sudo quotacheck -vucm \/mnt\/quota_test\r\n$ sudo quotacheck -vgcm \/mnt\/quota_test\r\n$ sudo quotaon -v \/mnt\/quota_test<\/pre>\n
You might need to install the quota utilities first. On Debian and Ubuntu the required package is called quota<\/em>. After finishing the operations above we get a new filesystem with user and group quotas enabled, available at \/mnt\/quota_test<\/em>. Take a note of output of the last command. It should be prefixed with \/dev\/loopN<\/em>, whereas N<\/em> is an arbitrary number. This device name will be needed later on.<\/p>\n
Syscalls in Go<\/h2>\n
Go’s standard library provides various functions for working directly with syscalls via its syscall<\/em> package. Fortunately, this package also defines the SYS_QUOTACTL<\/em> constant – holding the desired syscall number. Additionally the package provides some very handy helper functions – like BytePtrFromString<\/em> – to which we will get back to at a later point.<\/p>\n
The package further provides us with the Syscall<\/em> and Syscall6<\/em> functions, which issue syscalls. The first variant supports up to three arguments and Syscall6<\/em> – as its name suggests – supports up to six. As the quotactl<\/em> syscall requires four arguments, we will need to make use of Syscall6<\/em>.<\/p>\n
Digging through the man page<\/h2>\n
The quotactl(2)<\/em> man page explains the interface in detail. However, to start off we only need basic functionality, namely the ability to retrieve and set quotas. These operations are implemented through „subcommands“, Q_GETQUOTA<\/em>, which retrieves quota information, is documented to require a pointer to a specific data structure named dqblk<\/em>, which we will have to implement in Go.<\/p>\n
Another interesting detail we need to have a closer look at is how the cmd<\/em> argument to the quotactl<\/em> call is built. The man page references the QCMD(subcmd, type)<\/em> macro, which is defined in sys\/quota.h<\/em>, taking a „subcommand“ and a „quota type“, and applies a bitwise shift operation, followed by masking the type with an „AND“ operation.<\/p>\n
#define QCMD(cmd, type)  (((cmd) << SUBCMDSHIFT) | ((type) & SUBCMDMASK))<\/pre>\n
As we only want to be able to retrieve quota information, this newly aquired knowledge should suffice.<\/p>\n
Let’s Go<\/h2>\n
With all required information in hand, we define a wrapper similar to the one found in musl-libc<\/em> in Go:<\/p>\n
func quotactl(cmd int, special string, id int, target unsafe.Pointer) (err error) {\r\n  var deviceNamePtr *byte\r\n  if deviceNamePtr, err = syscall.BytePtrFromString(special); err != nil {\r\n    return\r\n  }\r\n  if _, _, errno := syscall.RawSyscall6(syscall.SYS_QUOTACTL, uintptr(cmd), uintptr(unsafe.Pointer(deviceNamePtr)), uintptr(id), uintptr(target), 0, 0); errno != 0 {\r\n    err = os.NewSyscallError(\"quotactl\", errno)\r\n  }\r\n  return\r\n}<\/pre>\n
As unsafe.Pointer<\/em> is used again and again, it is important to have a closer look at it. unsafe.Pointer<\/em> is possibly best compared to a void pointer in C. The type does not matter, we just need a pointer to data.<\/p>\n
Also, syscall.BytePtrFromString<\/em> is interesting when interacting at such a low level. This is required as Go’s string type is not compatible with NULL-terminated strings, as used in the kernel or in C. syscall.BytePtrFromString<\/em> converts a Go string into such a NULL-terminated string, which is represented as the pointer to its first byte.<\/p>\n
The target<\/em> argument is intentionally an unsafe.Pointer<\/em>, as quotactl<\/em> is able to fill other data structures, besides the mentioned dqblk<\/em>. Using this approach in the first place allows for easier extension later on. Which brings us right to dqblk<\/em>:<\/p>\n
type Dqblk struct {\r\n    DqbBHardlimit uint64\r\n    DqbBSoftlimit uint64\r\n    DqbCurSpace   uint64\r\n    DqbIHardlimit uint64\r\n    DqbISoftlimit uint64\r\n    DqbCurInodes  uint64\r\n    DqbBTime      uint64\r\n    DqbITime      uint64\r\n    DqbValid      uint32\r\n}<\/pre>\n
As you can see we can freely change the names of all fields, but we ensure the field order is preserved. Defining the required constants and a function implementing the QCMD<\/em> macro in Go is left as an exercise to the reader.<\/p>\n
Retrieving quota information<\/h2>\n
Now, having defined the data structures, and having converted the C-style snake-case identifiers to more Go-like camel case identifiers, we can implement the first public function which retrieves quotas:<\/p>\n
func GetQuota(typ int, special string, id int) (result *Dqblk, err error) {\r\n  result = &Dqblk{}\r\n  if err = quotactl(qCmd(qGetQuota, typ), special, id, unsafe.Pointer(result)); err != nil {\r\n    result = nil\r\n  }\r\n  return\r\n}<\/pre>\n
A sample invocation might be GetQuota(UsrQuota, „\/dev\/loop0“, 0),<\/em> which retrieves the user quota for UID 0 from „\/dev\/loop0“. Substitute \/dev\/loop0<\/em> with the device name, which was returned when the testbed was created and see what happens: the prototype works.<\/p>\n
Summary<\/h2>\n
This article has outlined the steps required for bringing low-level Linux kernel functionality to the world of Go. Retrieving filesystem quota information from the operating system was implemented in just a few lines of code. The approach taken \u2013 implementing the functionality natively in Go \u2013 allows creation of statically linked Go binaries without any external dependencies, which also greatly simplifies deployment.<\/p>\n
The full implementation of this example can be found at https:\/\/github.com\/anexia-it\/wad2018-quotactl<\/a> – containing the discussed pieces. A more complete Go filesystem quota library, which is based on the research that also led to this article, can be found at https:\/\/github.com\/anexia-it\/fsquota<\/a>.<\/p>\n
Hoping you enjoyed this journey into the depths of Go and kernel interfaces as much as I enjoyed working on this article.<\/p>\n","protected":false},"excerpt":{"rendered":"
Stephan demonstrate here how Go interacts with operating system and how he developed our quota library.<\/p>\n","protected":false},"author":5,"featured_media":4149,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1135],"tags":[1622,1626,1329,1624,1327],"yoast_head":"\nFilesystem quota management in Go - ANEXIA Blog<\/title>\n<meta name=\"description\" content=\"Stephan demonstrate here how Go interacts with operating system and how he developed our quota library.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/\" \/>\n<meta property=\"og:locale\" content=\"de_DE\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Filesystem quota management in Go - ANEXIA Blog\" \/>\n<meta property=\"og:description\" content=\"Stephan demonstrate here how Go interacts with operating system and how he developed our quota library.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/\" \/>\n<meta property=\"og:site_name\" content=\"ANEXIA Blog\" \/>\n<meta property=\"article:publisher\" content=\"https:\/\/www.facebook.com\/anexiagmbh\/\" \/>\n<meta property=\"article:published_time\" content=\"2018-04-24T06:11:09+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2022-04-21T11:31:05+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/anexia.com\/blog\/wp-content\/uploads\/2018\/04\/Stephan-Peijnik.jpg\" \/>\n\t<meta property=\"og:image:width\" content=\"1600\" \/>\n\t<meta property=\"og:image:height\" content=\"1066\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/jpeg\" \/>\n<meta name=\"author\" content=\"Stephan Peijnik\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@_ANEXIA\" \/>\n<meta name=\"twitter:site\" content=\"@_ANEXIA\" \/>\n<meta name=\"twitter:label1\" content=\"Verfasst von\" \/>\n\t<meta name=\"twitter:data1\" content=\"Stephan Peijnik\" \/>\n\t<meta name=\"twitter:label2\" content=\"Gesch\u00e4tzte Lesezeit\" \/>\n\t<meta name=\"twitter:data2\" content=\"6\u00a0Minuten\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/\",\"url\":\"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/\",\"name\":\"Filesystem quota management in Go - ANEXIA Blog\",\"isPartOf\":{\"@id\":\"https:\/\/anexia.com\/blog\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/#primaryimage\"},\"image\":{\"@id\":\"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/#primaryimage\"},\"thumbnailUrl\":\"https:\/\/anexia.com\/blog\/wp-content\/uploads\/2018\/04\/Stephan-Peijnik.jpg\",\"datePublished\":\"2018-04-24T06:11:09+00:00\",\"dateModified\":\"2022-04-21T11:31:05+00:00\",\"author\":{\"@id\":\"https:\/\/anexia.com\/blog\/#\/schema\/person\/8f95147348ae0ed7e4c25999bebf0f1d\"},\"description\":\"Stephan demonstrate here how Go interacts with operating system and how he developed our quota library.\",\"breadcrumb\":{\"@id\":\"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/#breadcrumb\"},\"inLanguage\":\"de\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"de\",\"@id\":\"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/#primaryimage\",\"url\":\"https:\/\/anexia.com\/blog\/wp-content\/uploads\/2018\/04\/Stephan-Peijnik.jpg\",\"contentUrl\":\"https:\/\/anexia.com\/blog\/wp-content\/uploads\/2018\/04\/Stephan-Peijnik.jpg\",\"width\":1600,\"height\":1066,\"caption\":\"Stephan-Peijnik\"},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/anexia.com\/blog\/de\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Filesystem quota management in Go\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/anexia.com\/blog\/#website\",\"url\":\"https:\/\/anexia.com\/blog\/\",\"name\":\"ANEXIA Blog\",\"description\":\"[:de] ANEXIA Blog - Technischen Themen, Anexia News und Insights [:]\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/anexia.com\/blog\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"de\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/anexia.com\/blog\/#\/schema\/person\/8f95147348ae0ed7e4c25999bebf0f1d\",\"name\":\"Stephan Peijnik\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"de\",\"@id\":\"https:\/\/anexia.com\/blog\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/0bfcb213a87f6c6c67ec494bc0ae5585?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/0bfcb213a87f6c6c67ec494bc0ae5585?s=96&d=mm&r=g\",\"caption\":\"Stephan Peijnik\"},\"url\":\"https:\/\/anexia.com\/blog\/author\/spe\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Filesystem quota management in Go - ANEXIA Blog","description":"Stephan demonstrate here how Go interacts with operating system and how he developed our quota library.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/","og_locale":"de_DE","og_type":"article","og_title":"Filesystem quota management in Go - ANEXIA Blog","og_description":"Stephan demonstrate here how Go interacts with operating system and how he developed our quota library.","og_url":"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/","og_site_name":"ANEXIA Blog","article_publisher":"https:\/\/www.facebook.com\/anexiagmbh\/","article_published_time":"2018-04-24T06:11:09+00:00","article_modified_time":"2022-04-21T11:31:05+00:00","og_image":[{"width":1600,"height":1066,"url":"https:\/\/anexia.com\/blog\/wp-content\/uploads\/2018\/04\/Stephan-Peijnik.jpg","type":"image\/jpeg"}],"author":"Stephan Peijnik","twitter_card":"summary_large_image","twitter_creator":"@_ANEXIA","twitter_site":"@_ANEXIA","twitter_misc":{"Verfasst von":"Stephan Peijnik","Gesch\u00e4tzte Lesezeit":"6\u00a0Minuten"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/","url":"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/","name":"Filesystem quota management in Go - ANEXIA Blog","isPartOf":{"@id":"https:\/\/anexia.com\/blog\/#website"},"primaryImageOfPage":{"@id":"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/#primaryimage"},"image":{"@id":"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/#primaryimage"},"thumbnailUrl":"https:\/\/anexia.com\/blog\/wp-content\/uploads\/2018\/04\/Stephan-Peijnik.jpg","datePublished":"2018-04-24T06:11:09+00:00","dateModified":"2022-04-21T11:31:05+00:00","author":{"@id":"https:\/\/anexia.com\/blog\/#\/schema\/person\/8f95147348ae0ed7e4c25999bebf0f1d"},"description":"Stephan demonstrate here how Go interacts with operating system and how he developed our quota library.","breadcrumb":{"@id":"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/#breadcrumb"},"inLanguage":"de","potentialAction":[{"@type":"ReadAction","target":["https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/"]}]},{"@type":"ImageObject","inLanguage":"de","@id":"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/#primaryimage","url":"https:\/\/anexia.com\/blog\/wp-content\/uploads\/2018\/04\/Stephan-Peijnik.jpg","contentUrl":"https:\/\/anexia.com\/blog\/wp-content\/uploads\/2018\/04\/Stephan-Peijnik.jpg","width":1600,"height":1066,"caption":"Stephan-Peijnik"},{"@type":"BreadcrumbList","@id":"https:\/\/anexia.com\/blog\/en\/filesystem-quota-management-in-go\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/anexia.com\/blog\/de\/"},{"@type":"ListItem","position":2,"name":"Filesystem quota management in Go"}]},{"@type":"WebSite","@id":"https:\/\/anexia.com\/blog\/#website","url":"https:\/\/anexia.com\/blog\/","name":"ANEXIA Blog","description":"[:de] ANEXIA Blog - Technischen Themen, Anexia News und Insights [:]","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/anexia.com\/blog\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"de"},{"@type":"Person","@id":"https:\/\/anexia.com\/blog\/#\/schema\/person\/8f95147348ae0ed7e4c25999bebf0f1d","name":"Stephan Peijnik","image":{"@type":"ImageObject","inLanguage":"de","@id":"https:\/\/anexia.com\/blog\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/0bfcb213a87f6c6c67ec494bc0ae5585?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/0bfcb213a87f6c6c67ec494bc0ae5585?s=96&d=mm&r=g","caption":"Stephan Peijnik"},"url":"https:\/\/anexia.com\/blog\/author\/spe\/"}]}},"lang":"en","translations":{"en":6685,"de":3447},"amp_enabled":true,"pll_sync_post":[],"_links":{"self":[{"href":"https:\/\/anexia.com\/blog\/wp-json\/wp\/v2\/posts\/6685"}],"collection":[{"href":"https:\/\/anexia.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/anexia.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/anexia.com\/blog\/wp-json\/wp\/v2\/users\/5"}],"replies":[{"embeddable":true,"href":"https:\/\/anexia.com\/blog\/wp-json\/wp\/v2\/comments?post=6685"}],"version-history":[{"count":1,"href":"https:\/\/anexia.com\/blog\/wp-json\/wp\/v2\/posts\/6685\/revisions"}],"predecessor-version":[{"id":6688,"href":"https:\/\/anexia.com\/blog\/wp-json\/wp\/v2\/posts\/6685\/revisions\/6688"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/anexia.com\/blog\/wp-json\/wp\/v2\/media\/4149"}],"wp:attachment":[{"href":"https:\/\/anexia.com\/blog\/wp-json\/wp\/v2\/media?parent=6685"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/anexia.com\/blog\/wp-json\/wp\/v2\/categories?post=6685"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/anexia.com\/blog\/wp-json\/wp\/v2\/tags?post=6685"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}