From 16a9f2072967775049ef6e1fd8af52ac67551cab Mon Sep 17 00:00:00 2001 From: "Michael (Parker) Parker" Date: Thu, 8 Jan 2026 10:58:05 -0500 Subject: [PATCH 1/2] Add Quota Documentation Updates the container width to fill more of the screen. This is better for the standard widescreen layouts. Add docker to the additionalLanguages for prism. Adds an "About Quotas" page with warnings. Adds documentation on enabling filesystem based quotas for EXT4. Adds Docs on advanced quota management section that covers EXT4. Adds empty pages for other filesystems is support is added. --- docs/guides/disk-quotas/about.mdx | 29 ++++ docs/guides/disk-quotas/btrfs.mdx | 0 docs/guides/disk-quotas/ext4-xfs.mdx | 226 +++++++++++++++++++++++++++ docs/guides/disk-quotas/lvm.mdx | 0 docs/guides/disk-quotas/zfs.mdx | 0 docs/wings/install.mdx | 5 + docusaurus.config.ts | 1 + sidebars.ts | 9 ++ src/css/custom.scss | 3 + 9 files changed, 273 insertions(+) create mode 100644 docs/guides/disk-quotas/about.mdx create mode 100644 docs/guides/disk-quotas/btrfs.mdx create mode 100644 docs/guides/disk-quotas/ext4-xfs.mdx create mode 100644 docs/guides/disk-quotas/lvm.mdx create mode 100644 docs/guides/disk-quotas/zfs.mdx diff --git a/docs/guides/disk-quotas/about.mdx b/docs/guides/disk-quotas/about.mdx new file mode 100644 index 00000000..162554d1 --- /dev/null +++ b/docs/guides/disk-quotas/about.mdx @@ -0,0 +1,29 @@ +import Admonition from '@theme/Admonition'; +import Link from '@docusaurus/Link'; + +# About Quotas + + + As called out in the Wings install docs. It is always recommended to keep the server files on a separate partition. + + +## There are a lot of notices here for a reason! + + + Support for disk quotas is still being worked on! + + + + These are advanced configurations meant for hosts but "should" work for individuals as well. + + + + Depending on the filesystem Quotas can be difficult to enable for the `/` mount, which requires booting a live disk to change. + + + + You can either make a new mount with quotas enabled or enable quotas on an existing partition. + + +## Filesystem specific docs +EXT4/XFS \ No newline at end of file diff --git a/docs/guides/disk-quotas/btrfs.mdx b/docs/guides/disk-quotas/btrfs.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/guides/disk-quotas/ext4-xfs.mdx b/docs/guides/disk-quotas/ext4-xfs.mdx new file mode 100644 index 00000000..8f819212 --- /dev/null +++ b/docs/guides/disk-quotas/ext4-xfs.mdx @@ -0,0 +1,226 @@ +import Admonition from '@theme/Admonition'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import Link from '@docusaurus/Link'; + +# EXT4 and XFS + +This page covers disk quota management for EXT4/XFS. + +Both EXT4 and XFS use the built in quota management services in linux. + + + Please read About Quotas before continuing + + +## Configure Filesystem +How to format and mount a device for use with quotas + +
+I understand the risks and Pelican is not Liable for anything that breaks + + + Enabling quotas for `/` is difficult, as it requires booting a live disk to change. + + We do not recommended this! + + +These examples use the following: +`/dev/sdb` as the device formated as EXT4 enabling only project quotas. +`/var/lib/pelican/volumes/` as the mount point and data directory + + + + ## Format Device + `mkfs.ext4` will format the disk with the ext4 filesystem + * The `O` flag is the enable Feature Options + - enable quotas while formatting + * The `E` flag is for Extented Options + - set the quota type as project + ```bash + mkfs.ext4 -O quota -E quotatype=prjquota /dev/sdb + ``` + + + You need to update fstab so the disk mounts automatically on boot with quotas enabled. + + + ## Add to fstab + ### get device UUID + The disk UUID is the best option for mounting the correct device via fstab. + ```bash + lsblk /dev/sdb -no UUID + # example output + 6c3b1734-3db4-4368-9bee-58651731b206 + ``` + + ### add new mount to fstab + ```shell title="/etc/fstab" {4} + # + # / was on /dev/sda1 during installation + UUID=8529a07b-28bc-4296-848a-a185aaf11e94 / ext4 errors=remount-ro 0 1 + UUID=6c3b1734-3db4-4368-9bee-58651731b206 /var/lib/pelican/volumes/ ext4 defaults,prjquota 0 1 + ``` + For more information on fstab check the [Arch Linux fstab docs](https://wiki.archlinux.org/title/Fstab) + + + Depending on the OS you may need to refresh services to be able to mount the partition after updating `fstab`. + + It is often easier to reboot and have the disk mount on boot. + + + + ## Update existing partition + Get the disk device path and uuid for your partition + + by default `findmnt` lists all mounts on the system and lists their source, fstype, and options + * The `n` flag disables headers + * The `o` flag only returns specified values + - `SOURCE` is device path + - `UUID` is the device id + ```bash + findmnt /var/lib/pelican/volumes -no SOURCE,UUID + ## example response + /dev/sdb 6c3b1734-3db4-4368-9bee-58651731b206 + ``` + + ## Unmount disk + Use `umount` to unmount the pelican volume mount. + ```bash + umount /var/lib/pelican/volumes/ + ``` + + ## Enable quotas + + This can only be ran on an unmounted disk + + `tune2fs` is used to adjust tunable file system parameters for EXT filesystems + * The `Q` flag is to manage quotas + - `prjquota` is to enable project quotas + * The device path is needed + ```bash + tune2fs -Q prjquota /dev/sdb + ``` + + ## update fstab entry + add `prjquota` to the line for the mount + from + ```shell title="/etc/fstab" + UUID=6c3b1734-3db4-4368-9bee-58651731b206 /var/lib/pelican/volumes/ ext4 defaults 0 1 + ``` + to + ```shell title="/etc/fstab" + UUID=6c3b1734-3db4-4368-9bee-58651731b206 /var/lib/pelican/volumes/ ext4 defaults,prjquota 0 1 + ``` + For more information on fstab check the [Arch Linux fstab docs](https://wiki.archlinux.org/title/Fstab) + + + Depending on the OS you may need to refresh services to be able to mount the partition after updating `fstab`. + + It is often easier to reboot and have the disk mount on boot. + + + +
+ +## Advanced EXT4 Quota Management + + The following section is for manual management of quotas. + + +
+I understand + + You should never need to go here, this is your last warning. + +
+I agree and Pelican is not Liable for anything that breaks + +## Manually Manage Quotas +Limits for the servers are managed on a "project" level so they can be assinged per-directory. + +### Add A New Project +To add a new project 2 files must be edited. + +First is the `projid` file which is formatted where each line is in the `project_name:project_id` format as seen below +* Pelican will use the server UUID as the project name +* Make sure the ID is not already being used. +```shell title="/etc/projid" +235844d3-9258-4846-bb04-bcff209ccf9a:1 +b91d5528-d53f-4586-8d5c-682027f74a36:2 +``` + +Second is the `projects` file which is formatted where each line is in the `project_id:path_to_directory` format as seen below +```shell title="/etc/projects" +1:/var/lib/pelican/volumes/235844d3-9258-4846-bb04-bcff209ccf9a +2:/var/lib/pelican/volumes/b91d5528-d53f-4586-8d5c-682027f74a36 +``` + +### Set directory attributes +The project attribute must be set on the directory to track quota usage. + +The `chattr` command changes attribute for files and directories. +* The `+` and `-` operators add or remove attributes + - The `P` makes it so files and directories created in the directory will inherit the project id of the directory. + - The project id and directory must match +* The `p` flag is for the project id +```bash +chattr +P -p ${project_id} ${path_to_directory} +``` + +Example: +```bash +chattr +P -p 1 /var/lib/pelican/volumes/235844d3-9258-4846-bb04-bcff209ccf9a +``` + +### set quota limits +The built in quota management uses blocks by default. +* You can specify limits in bytes as well. + +The `setquota` command sets the quota for any object that supports quotas. +* The `P` flag sets the quota for a project + - This can use the project `id` or `name` + - The should be the server UUID as shown in the examples below +* The soft limit would send a warning to a user + - This is not used by Pelican and will be set to 0 +* The hard limit is set to the disk resource limit set in the Pelican +* Neither the block or inode/file grace sections will be used by the Pelican. +* The path for either the device or the mount point + - `/dev/sdb/` or `/var/lib/pelican/volumes/` +```bash +setquota -P ${server_uuid} ${soft_limit} ${hard_limit} ${block_grace} ${inode_grace} ${path} +``` + +Example: +setting a hard limit, in Gigabytes +```bash +setquota -P 235844d3-9258-4846-bb04-bcff209ccf9a 0 10G 0 0 /var/lib/pelican/volumes/ +``` + +### get quota stats +The `repquota` command will generate a report on the quotas for the specified device or mount path +* The `P` flag will break down the report by project. + - In this case it should be the server UUID that is the project name +* The `--human-readable` flag sets the limits to be displayed in a human readable format. By default that is Megabytes + - `=g,g` changes the output to be in Gigabytes (can be `k`, `g`, `m`, or `t`) + +Example: +```bash +repquota -P --human-readable=g,g /var/lib/pelican/volumes/ # could also be /dev/sdb +``` + +Example Output +```shell + Block limits File limits +Project used soft hard grace used soft hard grace +---------------------------------------------------------------------- +235844d3-9258-4846-bb04-bcff209ccf9 -- 3G 0G 5G 1g 0g 0g +cdb26bbb-963d-44b1-8353-360243032b1 -- 2G 0G 2G 1g 0g 0g +``` + +
+
+ + + TODO: Add documentation specifically for XFS + \ No newline at end of file diff --git a/docs/guides/disk-quotas/lvm.mdx b/docs/guides/disk-quotas/lvm.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/guides/disk-quotas/zfs.mdx b/docs/guides/disk-quotas/zfs.mdx new file mode 100644 index 00000000..e69de29b diff --git a/docs/wings/install.mdx b/docs/wings/install.mdx index aac6adcb..32894926 100644 --- a/docs/wings/install.mdx +++ b/docs/wings/install.mdx @@ -6,6 +6,11 @@ import Admonition from '@theme/Admonition'; This software will not work on Windows operating systems. + + It is always recommended to keep the server files on a separate partition. + This prevents the root partition from filling and causing the host to crash, potentially becoming unbootable. + + ## Supported Systems The following is a list of supported operating systems. Please be aware that this is not an exhaustive list, diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 41cae8fa..ee5648d7 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -109,6 +109,7 @@ const config: Config = { "sql", "yaml", "php", + "docker" ], }, } satisfies Preset.ThemeConfig, diff --git a/sidebars.ts b/sidebars.ts index 6d8c5777..03622faf 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -56,6 +56,15 @@ const sidebars: SidebarsConfig = { 'guides/database-hosts', 'guides/change-panel-domain', 'guides/uninstalling', + + { + type: 'category', + label: 'Disk Quotas', + items: [ + 'guides/disk-quotas/about', + 'guides/disk-quotas/ext4-xfs', + ] + } ], }, 'troubleshooting', diff --git a/src/css/custom.scss b/src/css/custom.scss index 3545dec1..5e1144d0 100644 --- a/src/css/custom.scss +++ b/src/css/custom.scss @@ -19,6 +19,9 @@ --ifm-color-info-lighter: rgb(186, 230, 253); --ifm-color-info-lightest: rgb(240, 249, 255); + --ifm-container-width-xl: 1600px; + --ifm-container-width: 1280px; + --ifm-code-font-size: 95%; } From ccf26b765db258fb9944bf0957b2f8b6b32ccb25 Mon Sep 17 00:00:00 2001 From: MartinOscar <40749467+rmartinoscar@users.noreply.github.com> Date: Thu, 8 Jan 2026 18:20:06 +0100 Subject: [PATCH 2/2] Cleanup Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- docs/guides/disk-quotas/ext4-xfs.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/disk-quotas/ext4-xfs.mdx b/docs/guides/disk-quotas/ext4-xfs.mdx index 8f819212..58dd0d2c 100644 --- a/docs/guides/disk-quotas/ext4-xfs.mdx +++ b/docs/guides/disk-quotas/ext4-xfs.mdx @@ -137,10 +137,10 @@ These examples use the following: I agree and Pelican is not Liable for anything that breaks ## Manually Manage Quotas -Limits for the servers are managed on a "project" level so they can be assinged per-directory. +Limits for the servers are managed on a "project" level so they can be assigned per-directory. ### Add A New Project -To add a new project 2 files must be edited. +To add a new project, 2 files must be edited. First is the `projid` file which is formatted where each line is in the `project_name:project_id` format as seen below * Pelican will use the server UUID as the project name @@ -184,7 +184,7 @@ The `setquota` command sets the quota for any object that supports quotas. * The soft limit would send a warning to a user - This is not used by Pelican and will be set to 0 * The hard limit is set to the disk resource limit set in the Pelican -* Neither the block or inode/file grace sections will be used by the Pelican. +* Neither the block or inode/file grace sections will be used by the Pelican * The path for either the device or the mount point - `/dev/sdb/` or `/var/lib/pelican/volumes/` ```bash