LEDMatrix/docs/archive/PERMISSION_MANAGEMENT_GUIDE.md

Permission Management Guide

Overview

LEDMatrix runs with a dual-user architecture: the main display service runs as root (for hardware access), while the web interface runs as a regular user. This guide explains how to properly manage file and directory permissions to ensure both services can access the files they need.

Table of Contents

1. Why Permission Management Matters
2. Permission Utilities
3. When to Use Permission Utilities
4. How to Use Permission Utilities
5. Common Patterns and Examples
6. Permission Standards
7. Troubleshooting

---

Why Permission Management Matters

The Problem

Without proper permission management, you may encounter errors like:

• PermissionError: [Errno 13] Permission denied when saving config files
• PermissionError when downloading team logos
• Files created by the root service not accessible by the web user
• Files created by the web user not accessible by the root service

The Solution

The LEDMatrix codebase includes centralized permission utilities (src/common/permission_utils.py) that ensure files and directories are created with appropriate permissions for both users.

---

Permission Utilities

Available Functions

The permission utilities module provides the following functions:

Directory Management

• ensure_directory_permissions(path: Path, mode: int = 0o775) -> None
  • Creates directory if it doesn't exist
  • Sets permissions to the specified mode
  • Default mode: 0o775 (rwxrwxr-x) - group-writable

File Management

• ensure_file_permissions(path: Path, mode: int = 0o644) -> None
  • Sets permissions on an existing file
  • Default mode: 0o644 (rw-r--r--) - world-readable

Mode Helpers

These functions return the appropriate permission mode for different file types:

• get_config_file_mode(file_path: Path) -> int

  • Returns 0o640 for secrets files, 0o644 for regular config files

• get_assets_file_mode() -> int

  • Returns 0o664 (rw-rw-r--) for asset files (logos, images)

• get_assets_dir_mode() -> int

  • Returns 0o2775 (rwxrwsr-x) for asset directories
  • Setgid bit enforces inherited group ownership for new files/directories

• get_config_dir_mode() -> int

  • Returns 0o2775 (rwxrwsr-x) for config directories
  • Setgid bit enforces inherited group ownership for new files/directories

• get_plugin_file_mode() -> int

  • Returns 0o664 (rw-rw-r--) for plugin files

• get_plugin_dir_mode() -> int

  • Returns 0o2775 (rwxrwsr-x) for plugin directories
  • Setgid bit enforces inherited group ownership for new files/directories

• get_cache_dir_mode() -> int

  • Returns 0o2775 (rwxrwsr-x) for cache directories
  • Setgid bit enforces inherited group ownership for new files/directories

---

When to Use Permission Utilities

Always Use Permission Utilities When:

1. Creating directories - Use ensure_directory_permissions() instead of os.makedirs() or Path.mkdir()
2. Saving files - Use ensure_file_permissions() after writing files
3. Downloading assets - Set permissions after downloading logos, images, or other assets
4. Creating config files - Set permissions after saving configuration files
5. Creating cache files - Set permissions when creating cache directories or files
6. Plugin file operations - Set permissions when plugins create their own files/directories

You Don't Need Permission Utilities When:

1. Reading files - Reading doesn't require permission changes
2. Using core utilities - Core utilities (LogoHelper, CacheManager, ConfigManager) already handle permissions
3. Temporary files - Files in /tmp or created with tempfile don't need special permissions

---

How to Use Permission Utilities

Basic Import

from pathlib import Path
from src.common.permission_utils import (
    ensure_directory_permissions,
    ensure_file_permissions,
    get_assets_dir_mode,
    get_assets_file_mode,
    get_config_dir_mode,
    get_config_file_mode
)

Creating a Directory

Before (incorrect):

import os
os.makedirs("assets/sports/logos", exist_ok=True)
# Problem: Permissions may not be set correctly

After (correct):

from pathlib import Path
from src.common.permission_utils import ensure_directory_permissions, get_assets_dir_mode

logo_dir = Path("assets/sports/logos")
ensure_directory_permissions(logo_dir, get_assets_dir_mode())

Saving a File

Before (incorrect):

with open("config/my_config.json", 'w') as f:
    json.dump(data, f, indent=4)
# Problem: File may not be readable by root service

After (correct):

from pathlib import Path
from src.common.permission_utils import (
    ensure_directory_permissions,
    ensure_file_permissions,
    get_config_dir_mode,
    get_config_file_mode
)

config_path = Path("config/my_config.json")
# Ensure directory exists with proper permissions
ensure_directory_permissions(config_path.parent, get_config_dir_mode())

# Write file
with open(config_path, 'w') as f:
    json.dump(data, f, indent=4)

# Set file permissions
ensure_file_permissions(config_path, get_config_file_mode(config_path))

Downloading and Saving an Image

Before (incorrect):

response = requests.get(image_url)
with open("assets/sports/logo.png", 'wb') as f:
    f.write(response.content)
# Problem: File may not be writable by root service

After (correct):

from pathlib import Path
from src.common.permission_utils import (
    ensure_directory_permissions,
    ensure_file_permissions,
    get_assets_dir_mode,
    get_assets_file_mode
)

logo_path = Path("assets/sports/logo.png")
# Ensure directory exists
ensure_directory_permissions(logo_path.parent, get_assets_dir_mode())

# Download and save
response = requests.get(image_url)
with open(logo_path, 'wb') as f:
    f.write(response.content)

# Set file permissions
ensure_file_permissions(logo_path, get_assets_file_mode())

---

Common Patterns and Examples

Pattern 1: Config File Save

from pathlib import Path
from src.common.permission_utils import (
    ensure_directory_permissions,
    ensure_file_permissions,
    get_config_dir_mode,
    get_config_file_mode
)

def save_config(config_data: dict, config_path: str) -> None:
    """Save configuration file with proper permissions."""
    path = Path(config_path)
    
    # Ensure directory exists
    ensure_directory_permissions(path.parent, get_config_dir_mode())
    
    # Write file
    with open(path, 'w') as f:
        json.dump(config_data, f, indent=4)
    
    # Set permissions
    ensure_file_permissions(path, get_config_file_mode(path))

Pattern 2: Asset Directory Setup

from pathlib import Path
from src.common.permission_utils import (
    ensure_directory_permissions,
    get_assets_dir_mode
)

def setup_asset_directory(base_dir: str, subdir: str) -> Path:
    """Create asset directory with proper permissions."""
    asset_dir = Path(base_dir) / subdir
    ensure_directory_permissions(asset_dir, get_assets_dir_mode())
    return asset_dir

Pattern 3: Plugin File Creation

from pathlib import Path
from src.common.permission_utils import (
    ensure_directory_permissions,
    ensure_file_permissions,
    get_plugin_dir_mode,
    get_plugin_file_mode
)

def save_plugin_data(plugin_id: str, data: dict) -> None:
    """Save plugin data file with proper permissions."""
    plugin_dir = Path("plugins") / plugin_id
    data_file = plugin_dir / "data.json"
    
    # Ensure plugin directory exists
    ensure_directory_permissions(plugin_dir, get_plugin_dir_mode())
    
    # Write file
    with open(data_file, 'w') as f:
        json.dump(data, f, indent=2)
    
    # Set permissions
    ensure_file_permissions(data_file, get_plugin_file_mode())

Pattern 4: Cache Directory Creation

from pathlib import Path
from src.common.permission_utils import (
    ensure_directory_permissions,
    get_cache_dir_mode
)

def get_cache_directory() -> Path:
    """Get or create cache directory with proper permissions."""
    cache_dir = Path("/var/cache/ledmatrix")
    ensure_directory_permissions(cache_dir, get_cache_dir_mode())
    return cache_dir

Pattern 5: Atomic File Write with Permissions

from pathlib import Path
import tempfile
import os
from src.common.permission_utils import (
    ensure_directory_permissions,
    ensure_file_permissions,
    get_config_dir_mode,
    get_config_file_mode
)

def save_config_atomic(config_data: dict, config_path: str) -> None:
    """Save config file atomically with proper permissions."""
    path = Path(config_path)
    
    # Ensure directory exists
    ensure_directory_permissions(path.parent, get_config_dir_mode())
    
    # Write to temp file first
    temp_path = path.with_suffix('.tmp')
    with open(temp_path, 'w') as f:
        json.dump(config_data, f, indent=4)
    
    # Set permissions on temp file
    ensure_file_permissions(temp_path, get_config_file_mode(path))
    
    # Atomic move
    temp_path.replace(path)
    
    # Permissions are preserved after move, but ensure they're correct
    ensure_file_permissions(path, get_config_file_mode(path))

---

Permission Standards

File Permissions

File Type	Mode	Octal	Description
Config files	rw-r--r--	0o644	Readable by all, writable by owner
Secrets files	rw-r-----	0o640	Readable by owner and group only
Asset files	rw-rw-r--	0o664	Group-writable for root:user access
Plugin files	rw-rw-r--	0o664	Group-writable for root:user access

Directory Permissions

Directory Type	Mode	Octal	Description
Config directories	rwxrwsr-x	0o2775 (setgid)	Group-writable with setgid bit for inherited group ownership
Asset directories	rwxrwsr-x	0o2775 (setgid)	Group-writable with setgid bit for inherited group ownership
Plugin directories	rwxrwsr-x	0o2775 (setgid)	Group-writable with setgid bit for inherited group ownership
Cache directories	rwxrwsr-x	0o2775 (setgid)	Group-writable with setgid bit for inherited group ownership

Why These Permissions?

• Group-writable (664): Allows both root service and web user to read/write files
• Directory setgid bit (2775): Ensures new files and directories inherit the group ownership, maintaining consistent permissions
• World-readable (644): Config files need to be readable by root service
• Restricted (640): Secrets files should only be readable by owner and group

---

Troubleshooting

Common Issues

Issue: Permission denied when saving config

Symptoms:

PermissionError: [Errno 13] Permission denied: 'config/config.json'

Solution: Ensure you're using ensure_directory_permissions() and ensure_file_permissions():

from src.common.permission_utils import (
    ensure_directory_permissions,
    ensure_file_permissions,
    get_config_dir_mode,
    get_config_file_mode
)

path = Path("config/config.json")
ensure_directory_permissions(path.parent, get_config_dir_mode())
# ... write file ...
ensure_file_permissions(path, get_config_file_mode(path))

Issue: Logo downloads fail with permission errors

Symptoms:

PermissionError: Cannot write to directory assets/sports/logos

Solution: Use permission utilities when creating directories and saving files:

from src.common.permission_utils import (
    ensure_directory_permissions,
    ensure_file_permissions,
    get_assets_dir_mode,
    get_assets_file_mode
)

logo_path = Path("assets/sports/logos/team.png")
ensure_directory_permissions(logo_path.parent, get_assets_dir_mode())
# ... download and save ...
ensure_file_permissions(logo_path, get_assets_file_mode())

Issue: Files created by root service not accessible by web user

Symptoms:

• Web interface can't read files created by the service
• Files show as owned by root with restrictive permissions

Solution: Always use permission utilities when creating files. The utilities set group-writable permissions (664/775) that allow both users to access files.

Issue: Plugin can't write to its directory

Symptoms:

PermissionError: Cannot write to plugins/my-plugin/data.json

Solution: Use permission utilities in your plugin:

from src.common.permission_utils import (
    ensure_directory_permissions,
    ensure_file_permissions,
    get_plugin_dir_mode,
    get_plugin_file_mode
)

# In your plugin code
plugin_dir = Path("plugins") / self.plugin_id
ensure_directory_permissions(plugin_dir, get_plugin_dir_mode())
# ... create files ...
ensure_file_permissions(file_path, get_plugin_file_mode())

Verification

To verify permissions are set correctly:

# Check file permissions
ls -l config/config.json
# Should show: -rw-r--r-- or -rw-rw-r--

# Check directory permissions
ls -ld assets/sports/logos
# Should show: drwxrwxr-x or drwxr-xr-x

# Check if both users can access
sudo -u root test -r config/config.json && echo "Root can read"
sudo -u $USER test -r config/config.json && echo "User can read"

Manual Fix

If you need to manually fix permissions:

# Fix assets directory
sudo ./scripts/fix_perms/fix_assets_permissions.sh

# Fix plugin directory
sudo ./scripts/fix_perms/fix_plugin_permissions.sh

# Fix config directory
sudo chmod 755 config
sudo chmod 644 config/config.json
sudo chmod 640 config/config_secrets.json

---

Best Practices

1. Always use permission utilities when creating files or directories
2. Use the appropriate mode helper (get_assets_file_mode(), etc.) rather than hardcoding modes
3. Set directory permissions before creating files in that directory
4. Set file permissions immediately after writing the file
5. Use atomic writes (temp file + move) for critical files like config
6. Test with both users - verify files work when created by root service and web user

---

Integration with Core Utilities

Many core utilities already handle permissions automatically:

• LogoHelper (src/common/logo_helper.py) - Sets permissions when downloading logos
• LogoDownloader (src/logo_downloader.py) - Sets permissions for directories and files
• CacheManager - Sets permissions when creating cache directories
• ConfigManager - Sets permissions when saving config files
• PluginManager - Sets permissions for plugin directories and marker files

If you're using these utilities, you don't need to manually set permissions. However, if you're creating files directly (not through these utilities), you should use the permission utilities.

---

Summary

• Always use ensure_directory_permissions() when creating directories
• Always use ensure_file_permissions() after writing files
• Use mode helpers (get_assets_file_mode(), etc.) for consistency
• Core utilities handle permissions - you only need to set permissions for custom file operations
• Group-writable permissions (664/775) allow both root service and web user to access files

For questions or issues, refer to the troubleshooting section or check existing code in the LEDMatrix codebase for examples.