PacManager.hpp

1. Overview

The PacManager.hpp header defines the PacManager class, responsible for managing Proxy Auto-Configuration (PAC) settings across multiple desktop environments and execution contexts. This component provides a unified interface for enabling, disabling, and supervising PAC-based proxy configuration on Linux systems.

Functionally, PacManager provides:

  • Cross-desktop PAC configuration management (GNOME, KDE, XFCE)
  • Fallback proxy handling for headless and CLI environments
  • Integration with user-level PAC daemons
  • Standardized result reporting with diagnostic information
  • Command-based backend detection and execution

2. Dependencies and Includes

#include <string>
  • <string> – storage of PAC URLs, backend identifiers, and diagnostic messages

3. Class Declaration and Scope

class PacManager

The PacManager class is implemented as a static utility controller. It does not require instantiation and exposes all functionality through static member functions.

4. Result Structure

struct Result {
    bool ok = false;
    std::string backend;
    std::string message;
};

Represents the outcome of a PAC management operation, including execution status, selected backend, and diagnostic output.

  • ok – indicates whether the operation completed successfully
  • backend – selected configuration backend (gnome, kde, xfce, env, none)
  • message – human-readable log or diagnostic information

5. Public Interface

5.1 PAC Enable/Disable

static Result enable_pac(const std::string& pac_url);
static Result disable_pac();

Enables or disables automatic proxy configuration using the specified PAC URL. When disabled, the system is restored to direct connection mode or to a previously recorded configuration state.

5.2 PAC Daemon Control

static Result start_pacd_user();
static Result stop_pacd_user();

Starts or stops the user-level PAC daemon, when supported by the environment. This daemon may be responsible for evaluating and distributing PAC settings.

5.3 Combined Convenience Operations

static Result enable_pac_with_pacd(const std::string& pac_url);
static Result disable_pac_with_pacd();

High-level helper functions that combine PAC configuration with daemon lifecycle management for simplified deployment and teardown.

6. Backend Detection and Command Execution

6.1 Command Availability Check

static bool cmd_exists(const std::string& cmd);

Determines whether a given system command is available in the execution environment. This method is used to detect supported desktop backends and utilities.

6.2 Command Runner

static int run_cmd(const std::string& cmd,
                   std::string* out = nullptr);

Executes a shell command and optionally captures its output for diagnostic purposes. The return value represents the process exit status.

7. Desktop Environment Backends

7.1 GNOME Backend

static Result enable_gnome(const std::string& pac_url);
static Result disable_gnome();

Configures PAC settings using GNOME system settings (typically via gsettings).

7.2 KDE Backend

static Result enable_kde(const std::string& pac_url);
static Result disable_kde();

Applies PAC configuration using KDE Plasma network and proxy configuration tools.

7.3 XFCE Backend

static Result enable_xfce(const std::string& pac_url);
static Result disable_xfce();

Manages proxy settings through XFCE configuration channels and utilities.

8. Headless and Environment Fallback

static Result enable_env_fallback();
static Result disable_env_fallback();

Provides a fallback mechanism for non-GUI or service environments by configuring proxy-related environment variables. This mode does not rely on PAC evaluation and is primarily intended for CLI tools and background services.

9. Execution Strategy

PacManager selects the most appropriate backend at runtime by detecting available desktop services and commands. Operations are executed in the following order:

  • Detect supported desktop environment
  • Validate PAC URL format and accessibility
  • Apply backend-specific configuration
  • Start or stop auxiliary services as required
  • Return a structured Result object

10. Security and Operational Considerations

  • Command sanitization: all shell commands must be constructed using validated and escaped input to prevent injection vulnerabilities
  • Privilege handling: backend configuration may require elevated permissions depending on system policies
  • URL validation: PAC URLs should be restricted to trusted schemes and locations (e.g., file://, https://)
  • Rollback strategy: failed configuration attempts should restore the previous proxy state where possible
  • Audit logging: configuration changes should be logged for troubleshooting and compliance
  • Compatibility testing: behavior should be validated across supported desktop environments and distributions
Published on:
Last updated on: