fairshare

Fair resource allocation for shared Linux systems

A lightweight resource manager that prevents any single user from monopolizing CPU and memory on multi-user Linux servers. fairshare automatically enforces per-user limits while allowing users to request additional resources dynamically when they need them.

The Problem fairshare Solves

On shared Linux systems, one user running a heavy workload can consume all available CPU and memory, leaving nothing for other users. This creates a terrible experience and reduces productivity.

The Solution

fairshare allocates resources fairly across all users:

• Default: Each user gets 1 CPU core, 2GB RAM, and optional disk quota by default
• Reserved: System reserves resources for OS and background processes (2 CPUs, 4GB RAM, 4GB disk by default)
• On-demand: Users can request more resources when needed (up to 1000 CPU cores and 10000 GB RAM)
• Automatic: The system grants requests only if resources are truly available
• Fair: No user can monopolize the entire system

Installation

Quick Install (Recommended)

The easiest way to install fairshare is using the installation script:

# Download and run the installer
curl -sSL https://raw.github.com/WilliamJudge94/fairshare/main/install.sh | bash

Or if you prefer to inspect the script first:

# Download the installer
wget https://raw.github.com/WilliamJudge94/fairshare/main/install.sh

# Review it
cat install.sh

# Run it
bash install.sh

The installer will:

• Detect if PolicyKit is installed (automatically installs it if missing)
• Download the latest release binary for your architecture
• Install the binary and wrapper script
• Set up PolicyKit policies
• Configure default resource limits (1 CPU core, 2GB RAM per user)
• Set system reserves (2 CPUs, 4GB RAM by default)

Build from Source

If you prefer to build from source or are developing fairshare:

# 1. Build the release binary
cargo build --release

# 2. Run the installer (it will detect the local build and install PolicyKit if needed)
bash install.sh

Alternatively, use the Makefile for manual installation:

# Build and install binary and wrapper
cargo build --release
sudo make release

# Ensure PolicyKit is installed (required for fairshare to work)
# Debian/Ubuntu
sudo apt install policykit-1

# Fedora/RHEL
sudo dnf install polkit

# Arch Linux
sudo pacman -S polkit

# Setup admin defaults and PolicyKit policies (REQUIRED)
sudo fairshare admin setup --cpu 1 --mem 2

What Gets Installed

• /usr/local/bin/fairshare - Wrapper script (user-facing command)
• /usr/local/libexec/fairshare-bin - Real binary (internal use only)
• PolicyKit policies - Allow passwordless execution for active users
• Systemd configuration - Default resource limits for all user slices

The wrapper script automatically detects whether you're running an admin command (requires sudo) or a regular user command (automatically uses pkexec).

Requirements

• Linux with systemd (including user session support)
• PolicyKit (polkit) for privilege escalation (automatically installed by the installer if missing)
• Rust 1.70+ (only needed for building from source)
• GLIBC 2.31+ (compatible with RHEL 9, Debian 11+, Ubuntu 20.04+, and most modern distributions)

Compatibility Notes

Release binaries are built with GLIBC 2.31 for maximum compatibility:

• ✅ RHEL 9+ (GLIBC 2.34)
• ✅ Debian 11+ (GLIBC 2.31)
• ✅ Ubuntu 20.04+ (GLIBC 2.31)
• ✅ Rocky Linux 9+ (GLIBC 2.34)
• ✅ AlmaLinux 9+ (GLIBC 2.34)

If you encounter GLIBC version errors, try building from source on your system.

Uninstall

To remove fairshare from your system:

# Using the uninstall script
curl -sSL https://raw.github.com/WilliamJudge94/fairshare/main/uninstall.sh | bash

# Or if you have the repository
bash uninstall.sh

# Or manually
sudo fairshare admin uninstall --force

Usage Guide

User Commands (No sudo required)

Regular users can manage their own resource allocations. The wrapper script automatically handles privilege escalation via PolicyKit, so you don't need to type pkexec or sudo.

1. Check System Status

See how much CPU and memory is available and what each user is currently using.

fairshare status

2. Check Your Current Allocation

View how much CPU and memory your user session has access to.

fairshare info

3. Request Resources

Ask for CPU and memory resources. The system uses smart delta-based checking - it only needs enough free resources to cover the increase from your current allocation.

fairshare request --cpu 4 --mem 8

Smart Allocation Example:

• You currently have: 9GB RAM allocated
• System has: 2GB free
• You request: 10GB RAM
• Result: SUCCESS (net increase is only 1GB, which fits in the 2GB available)

Constraints:

• CPU: 1–1000 cores
• Memory: 1–10000 GB

4. Release Resources

Return your resources to the system and revert to the default allocation (1 CPU core, 2GB RAM).

fairshare release

Administrator Commands (Requires sudo)

Note: Admin commands must be run with sudo

Set Default Limits and System Reserves

Configure the default CPU, memory, and disk allocation for all users when they first log in, plus system reserves. This also installs PolicyKit policies required for passwordless user operations.

# Setup with defaults (1 CPU, 2GB RAM per user, 2 CPU reserve, 4GB RAM reserve)
sudo fairshare admin setup --cpu 1 --mem 2 --cpu-reserve 2 --mem-reserve 4

# Or use custom values
sudo fairshare admin setup --cpu 2 --mem 4 --cpu-reserve 4 --mem-reserve 8

# With optional disk quota on a specific partition
sudo fairshare admin setup --cpu 1 --mem 2 --disk 10 --disk-partition /home

# Disk quota on a different partition (e.g., /data, /mnt)
sudo fairshare admin setup --cpu 1 --mem 2 --disk 10 --disk-partition /mnt

# Disk quota with custom reserve
sudo fairshare admin setup --cpu 1 --mem 2 --disk 10 --disk-partition /home --disk-reserve 5

Disk Quota Options (Optional):

Disk quotas are optional. If you don't specify --disk and --disk-partition, fairshare will only manage CPU and memory limits.

• --disk <GB>: Set default disk quota per user in gigabytes (1-10000 GB)
• --disk-partition <path>: Mount point where quotas will be enforced (e.g., /home, /mnt, /data)
• --disk-reserve <GB>: Reserve disk space for system use (default: 4GB)

Note: Both --disk and --disk-partition must be specified together to enable disk quotas.

Disk Quota Requirements:

Important: Disk quotas require filesystem-level quota support to be enabled.

For quotas to work, you must:

1. Enable quotas in /etc/fstab with mount options like usrquota or quota
2. For ext4: Enable the quota feature with tune2fs -O quota /dev/sdX and run quotaon
3. For XFS: Quotas are typically enabled at mount time with uquota option

Tested Filesystems:

• XFS - Fully tested and working
• ext4 - Fully tested and working
• btrfs, other filesystems - May work but not yet tested (low confidence)

What Reserves Do: System reserves ensure that CPU, memory, and disk space are always available for the operating system and background processes. Users can only allocate up to (Total - Reserved) resources.

Example on an 8 CPU, 16GB RAM, 100GB disk system:

• Total: 8 CPUs, 16GB RAM, 100GB disk
• Reserved: 2 CPUs, 4GB RAM, 4GB disk (default)
• Available for users: 6 CPUs, 12GB RAM, 96GB disk

Force-Set Resources for a Specific User

Administrators can directly set resource allocations for any user on the system, even if that user is not currently logged in.

# Set resources by username
sudo fairshare admin set-user --user alice --cpu 4 --mem 8 --disk 8

# Set resources by UID
sudo fairshare admin set-user --user 1000 --cpu 2 --mem 4 --disk 8

# Force set without confirmation prompt (for scripts)
sudo fairshare admin set-user --user bob --cpu 10 --mem 20 --disk 40 --force

Key Features:

• Works with username (e.g., "alice") or UID (e.g., "1000")
• Checks resource availability and warns if allocation exceeds system capacity
• Prompts for confirmation when over-allocating (unless --force is used)
• Works even when the target user is signed out
• Cannot modify root (UID 0) or system users (UID < 1000)

Resource Availability Warning: If the allocation would exceed available resources, the command displays a warning about potential resource contention and prompts for confirmation. Use --force to skip the prompt for automated scripts.

Uninstall fairshare

Remove fairshare from your system and revert to standard Linux resource management.

sudo fairshare admin uninstall --force

How It Works

Architecture

fairshare uses a wrapper script pattern to provide a seamless user experience:

1. User types: fairshare status
2. Wrapper detects: Not an admin command
3. Wrapper calls: pkexec /usr/local/libexec/fairshare-bin status
4. PolicyKit checks: User is active → allow without password
5. Binary executes: Reads PKEXEC_UID to identify calling user
6. systemd query: Only queries/modifies the calling user's slice

This architecture ensures:

• Simple UX - No pkexec in commands
• Security - Users can only manage their own resources
• Proper privilege separation - Wrapper handles escalation transparently

Resource Management

fairshare uses systemd as the authoritative source of truth for all resource allocations:

1. Resource Tracking: All allocations are stored directly in systemd user slices (user-{UID}.slice)
2. Dynamic Querying: The system queries systemd in real-time to get current allocations (no persistent state file)
3. Delta-Based Checking: When you request resources, fairshare calculates the net change from your current allocation
4. Privilege Escalation: Uses pkexec (PolicyKit) to allow users to modify their own slices without full root access

Troubleshooting

PolicyKit (pkexec) not found

If you see an error that pkexec is not found, PolicyKit is not installed. Install it using:

# Debian/Ubuntu
sudo apt update && sudo apt install -y policykit-1

# Fedora/RHEL
sudo dnf install -y polkit

# Arch Linux
sudo pacman -S --noconfirm polkit

After installing PolicyKit, fairshare should work immediately (no need to reinstall fairshare).

Commands fail with "authentication required" or "permission denied"

If PolicyKit authentication keeps prompting for password, verify that admin setup completed successfully:

sudo fairshare admin setup --cpu 1 --mem 2

This installs the PolicyKit policies that allow active users to run fairshare commands without entering a password.

Wrapper not found or binary not found

If you get "command not found" errors, ensure the installation completed:

# Reinstall using the install script
bash install.sh

# Or if building from source
sudo make release

# Verify installation
which fairshare              # Should show /usr/local/bin/fairshare
ls -l /usr/local/libexec/fairshare-bin  # Should exist

Resource request fails even though resources seem available

Remember that fairshare uses delta-based checking. Check your current allocation:

fairshare info

Then check system-wide availability:

fairshare status

Your request fails only if the net increase exceeds available resources.

Changes don't take effect

After running sudo fairshare admin setup, systemd needs to reload:

sudo systemctl daemon-reload

Disk quota fails or shows warnings

Disk quotas require filesystem-level support. If you see quota-related warnings:

1. Check if quotas are enabled in fstab:

   cat /etc/fstab | grep -E 'usrquota|quota|uquota'

2. For ext4 filesystems:

   # Enable quota feature (unmount first if possible, or use -f)
   sudo tune2fs -O quota /dev/sdX
   
   # Turn on quotas
   sudo quotaon /mount/point

3. For XFS filesystems: XFS typically needs quotas enabled at mount time. Add uquota to fstab:

   /dev/sdX  /home  xfs  defaults,uquota  0 0
   

   Then remount: sudo mount -o remount /home

4. Verify quotas are working:

   sudo repquota -u /mount/point

Note: fairshare has been tested with XFS and ext4 filesystems. Other filesystems (btrfs, etc.) may work but are not yet verified.

Quick testing tip

If you want a clean, preconfigured environment with systemd and cgroups available out of the box, GitHub Codespaces can be a convenient option for running and testing fairshare. Refer the Guide

License

This project is open source.