LLAPI_QUOTACTL(3)

📦 version 2.17.58, in ubuntu stonking

✨ LLAPI_QUOTACTL ✨

okay bestie, welcome to the llapi_quotactl(3) page, aka the Lustre Library Functions girlies' guide to manipulating disk quotas on a Lustre filesystem 💅 like yes we're literally doing quota admin and we're gonna be so cute about it.

no cap, this one's from the Lustre User API corner of the manual, section 3, and it's genuinely iconic for anyone running a Lustre filesystem. let's go 🦋

🌸 NAME 🌸

ok so like, the whole point: llapi_quotactl — manipulate disk quotas on a Lustre filesystem. that's the vibe. that's the function. periodt.

✨ SYNOPSIS ✨

first thing first, you gotta bring in the header or nothing works, bestie:

#include <lustre/lustreapi.h>

int llapi_quotactl(char *mnt, struct if_quotactl *qctl);

and here's the lil struct lineup you're working with — copy these exactly, i'm not playing:

struct if_quotactl {
        __u32                   qc_cmd;
        __u32                   qc_type;
        __u32                   qc_id;
        __u32                   qc_stat;
        struct obd_dqinfo       qc_dqinfo;
        struct obd_dqblk        qc_dqblk;
        char                    obd_type[16];
        struct obd_uuid         obd_uuid;
};

struct obd_dqblk {
        __u64 dqb_bhardlimit;
        __u64 dqb_bsoftlimit;
        __u64 dqb_curspace;
        __u64 dqb_ihardlimit;
        __u64 dqb_isoftlimit;
        __u64 dqb_curinodes;
        __u64 dqb_btime;
        __u64 dqb_itime;
        __u32 dqb_valid;
        __u32 padding;
};

struct obd_dqinfo {
        __u64 dqi_bgrace;
        __u64 dqi_igrace;
        __u32 dqi_flags;
        __u32 dqi_valid;
};

struct obd_uuid {
        char uuid[40];
};

💖 DESCRIPTION 💖

so the llapi_quotactl() function manipulates disk quotas on a Lustre filesystem mnt. and qc_cmd is the command you're throwing at UID qc_id or GID qc_id — your pick, main character energy either way 👑

here's the command menu, one by one, no skips:

  • LUSTRE_Q_QUOTAON — turn on quotas for a Lustre filesystem. ok so heads up: this one is Deprecated as of 2.4.0 😭. qc_type is USRQUOTA, GRPQUOTA or UGQUOTA (that's both user and group quotas, bestie). and the quota files must exist — they're normally created with the llapi_quotacheck(3) call.
this call is restricted to the super-user. like, actual super-user. don't try it.
  • LUSTRE_Q_QUOTAOFF — turn off quotas for a Lustre filesystem. also Deprecated as of 2.4.0 🙈. qc_type is USRQUOTA, GRPQUOTA or UGQUOTA (both user and group quotas).
again: this call is restricted to the super-user.
  • LUSTRE_Q_GETQUOTA — get disk quota limits and current usage for user or group qc_id. qc_type is USRQUOTA or GRPQUOTA. uuid may be filled with an OBD UUID string to query quota information from a specific node. dqb_valid may be set nonzero to query information only from MDS. and if uuid is an empty string and dqb_valid is zero, then you get the clusterwide limits and usage back. on return obd_dqblk contains the requested information (heads up: block limits unit is kilobyte). dqb_btime and dqb_itime are the block and inode softlimit grace period expiration timestamps for the requested user or group 🕐
quotas must be turned on before using this command. fr fr.
  • LUSTRE_Q_SETQUOTA — set disk quota limits for user or group qc_id. qc_type is USRQUOTA or GRPQUOTA. dqb_valid must be set to QIF_ILIMITS, QIF_BLIMITS or QIF_LIMITS (that's both inode limits and block limits) depending on what limits you're updating. obd_dqblk must be filled with limit values (as set in dqb_valid, and yes, block limits unit is kilobyte).
quotas must be turned on before using this command too. obviously 💅
  • LUSTRE_Q_GETINFO — get information about quotas. qc_type is either USRQUOTA or GRPQUOTA. on return, dqi_igrace is the default inode grace period duration for all users or all groups (in seconds), dqi_bgrace is the default block grace period duration for all users or all groups (in seconds), and dqi_flags is not used by the current Lustre version — so like, don't expect anything from it.
  • LUSTRE_Q_SETINFO — set quota information (like grace times, bestie ⏳). qc_type is either USRQUOTA or GRPQUOTA. dqi_igrace is inode grace time (in seconds), dqi_bgrace is block grace time (in seconds), and dqi_flags is not used by the current Lustre version and must be zeroed.

⭐ RETURN VALUES ⭐

llapi_quotactl() returns:

  • 0 — on success. slay ✨
  • -1 — on failure, and it sets errno to indicate the error. 😭

💀 ERRORS 💀

ok so when things go wrong (and they might), here's what errno is telling you:

  • EFAULT — qctl is invalid.
  • ENOSYS — the kernel or Lustre modules have not been compiled with the QUOTA option.
  • ENOMEM — insufficient memory to complete operation.
  • ENOTTY — qc_cmd is invalid.
  • EBUSY — cannot process during quotacheck.
  • ENOENT — uuid does not correspond to OBD or mnt does not exist.
  • EPERM — the call is privileged and the caller was not the super-user.
  • ESRCH — no disk quota is found for the indicated user.
and also: quotas have not been turned on for this filesystem. double-check that before you spiral 🫶

🌈 AVAILABILITY 🌈

llapi_quotactl() is part of the lustre(7) user application interface library since release 2.4.0. she's been here a minute, and she's still serving 👑

🎀 SEE ALSO 🎀

ok that's the whole page bestie, you're officially quota-literate 💜 this lil masterpiece came to you from the Lustre User API crew, dated 2024-08-28, and it's the LLAPI_QUOTACTL(3) page in all her glory. mwah. go forth and quota responsibly 🧚✨

📦 where this page comes from