Skip to content

Configuration

Jump to bottom Edit New page
Tuhin Garai edited this page Jul 3, 2025 · 2 revisions

Configuration

Advanced configuration options for customizing BravePurifier behavior and Brave Browser settings.

🔧 Script Configuration

Environment Variables

You can customize BravePurifier behavior using environment variables:

# Skip dependency installation
export SKIP_DEPS=true

# Force specific package manager
export FORCE_PM="apt"

# Custom policy directory
export POLICY_DIR="/custom/path/policies"

# Verbose output
export VERBOSE=true

# Skip user settings application
export SKIP_USER_SETTINGS=true

Command Line Options

# Show help
./brave-purifier.sh --help

# Show version
./brave-purifier.sh --version

# Dry run (show what would be done)
./brave-purifier.sh --dry-run

# Force reinstall
./brave-purifier.sh --force

📁 Policy Configuration

System-Wide Policies

Policies are stored in /etc/brave/policies/managed/privacy-policy.json

Core Privacy Policies

{
    "MetricsReportingEnabled": false,
    "SafeBrowsingEnabled": false,
    "SearchSuggestEnabled": false,
    "SyncDisabled": true,
    "AutofillAddressEnabled": false,
    "AutofillCreditCardEnabled": false,
    "PasswordManagerEnabled": false
}

Content Blocking Policies

{
    "DefaultNotificationsSetting": 2,
    "DefaultGeolocationSetting": 2,
    "DefaultCamerasSetting": 2,
    "DefaultMicrophonesSetting": 2,
    "DefaultPopupsSetting": 2,
    "DefaultCookiesSetting": 4
}

Brave-Specific Policies

{
    "BraveRewardsDisabled": true,
    "BraveWalletDisabled": true,
    "BraveVPNDisabled": true,
    "BraveNewsDisabled": true,
    "BraveTalkDisabled": true
}

Custom Policy Creation

Create custom policies for specific needs:

# Create custom policy file
sudo mkdir -p /etc/brave/policies/managed/
sudo nano /etc/brave/policies/managed/custom-policy.json

Example custom policy:

{
    "HomepageLocation": "https://duckduckgo.com",
    "RestoreOnStartup": 4,
    "RestoreOnStartupURLs": ["https://duckduckgo.com"],
    "BookmarkBarEnabled": true,
    "ShowHomeButton": true
}

👤 User-Specific Configuration

User Preferences

User settings are stored in ~/.config/BraveSoftware/Brave-Browser/Default/Preferences

Privacy Settings

{
    "profile": {
        "default_content_setting_values": {
            "geolocation": 2,
            "media_stream_camera": 2,
            "media_stream_mic": 2,
            "notifications": 2,
            "popups": 2
        }
    }
}

Search Configuration

{
    "default_search_provider": {
        "enabled": true,
        "name": "DuckDuckGo",
        "search_url": "https://duckduckgo.com/?q={searchTerms}&t=brave",
        "suggest_url": ""
    }
}

Per-User Customization

Apply different settings for different users:

# Create user-specific script
sudo nano /usr/local/bin/brave-user-config.sh
#!/bin/bash
USER_HOME="/home/$1"
BRAVE_DIR="$USER_HOME/.config/BraveSoftware/Brave-Browser/Default"

# Custom preferences for specific user
cat > "$BRAVE_DIR/Preferences" << 'EOF'
{
    "brave": {
        "new_tab_page": {
            "show_background_image": true,
            "show_clock": true
        }
    }
}
EOF

chown -R "$1:$1" "$USER_HOME/.config/BraveSoftware"

🛡️ Security Configuration

Enhanced Security Policies

For high-security environments:

{
    "DeveloperToolsAvailability": 2,
    "ExtensionInstallBlocklist": ["*"],
    "DefaultJavaScriptSetting": 2,
    "DefaultPluginsSetting": 2,
    "RemoteAccessHostFirewallTraversal": false,
    "EnableMediaRouter": false
}

Network Security

{
    "WebRTCIPHandlingPolicy": "disable_non_proxied_udp",
    "NetworkPredictionOptions": 2,
    "DnsOverHttpsMode": "secure",
    "DnsOverHttpsTemplates": "https://cloudflare-dns.com/dns-query"
}

🔍 Search Engine Configuration

Default Search Engines

Configure alternative search engines:

DuckDuckGo (Default)

{
    "name": "DuckDuckGo",
    "search_url": "https://duckduckgo.com/?q={searchTerms}&t=brave",
    "suggest_url": ""
}

Startpage

{
    "name": "Startpage",
    "search_url": "https://www.startpage.com/sp/search?query={searchTerms}",
    "suggest_url": ""
}

Searx

{
    "name": "Searx",
    "search_url": "https://searx.org/search?q={searchTerms}",
    "suggest_url": ""
}

🎨 Interface Configuration

New Tab Page Customization

{
    "brave": {
        "new_tab_page": {
            "hide_all_widgets": false,
            "show_background_image": true,
            "show_clock": true,
            "show_stats": true,
            "show_top_sites": false,
            "show_rewards": false
        }
    }
}

Toolbar Configuration

{
    "bookmark_bar": {
        "show_on_all_tabs": true
    },
    "browser": {
        "show_home_button": true
    }
}

🔌 Extension Configuration

Allowed Extensions

Create whitelist for trusted extensions:

{
    "ExtensionInstallBlocklist": ["*"],
    "ExtensionInstallAllowlist": [
        "cjpalhdlnbpafiamejdnhcphjbkeiagm",  // uBlock Origin
        "gcbommkclmclpchllfjekcdonpmejbdp",  // HTTPS Everywhere
        "pkehgijcmpdhfbdbbnkijodmdjhbjlgp"   // Privacy Badger
    ]
}

Extension Policies

{
    "ExtensionSettings": {
        "cjpalhdlnbpafiamejdnhcphjbkeiagm": {
            "installation_mode": "force_installed",
            "update_url": "https://clients2.google.com/service/update2/crx"
        }
    }
}

📊 Monitoring Configuration

Logging Settings

Enable specific logging for troubleshooting:

# Enable verbose logging
brave-browser --enable-logging --log-level=0 --v=1

# Log specific components
brave-browser --enable-logging --vmodule=brave_shields*=1

Performance Monitoring

{
    "PerformanceMonitoringEnabled": false,
    "MetricsReportingEnabled": false,
    "HeartbeatEnabled": false
}

🔄 Update Configuration

Automatic Updates

Control update behavior:

{
    "AutoUpdateCheckPeriodMinutes": 0,
    "UpdatesSuppressed": true,
    "ComponentUpdatesEnabled": false
}

Manual Update Control

# Disable automatic updates
sudo systemctl disable brave-browser-update.service
sudo systemctl mask brave-browser-update.service

🛠️ Advanced Configuration

Command Line Flags

Create custom launcher with specific flags:

# Create custom launcher
sudo nano /usr/local/bin/brave-private
#!/bin/bash
exec /usr/bin/brave-browser \
    --disable-background-networking \
    --disable-background-timer-throttling \
    --disable-backgrounding-occluded-windows \
    --disable-renderer-backgrounding \
    --disable-features=TranslateUI \
    --disable-ipc-flooding-protection \
    --disable-client-side-phishing-detection \
    --disable-component-update \
    --disable-default-apps \
    --disable-domain-reliability \
    --disable-extensions \
    --disable-features=AutofillServerCommunication \
    --disable-hang-monitor \
    --disable-prompt-on-repost \
    --disable-sync \
    --disable-web-security \
    --no-default-browser-check \
    --no-first-run \
    --no-pings \
    --no-service-autorun \
    --password-store=basic \
    --use-mock-keychain \
    "$@"

Profile Management

Create isolated profiles:

# Create work profile
brave-browser --user-data-dir=/home/user/.config/brave-work

# Create personal profile
brave-browser --user-data-dir=/home/user/.config/brave-personal

📝 Configuration Validation

Verify Policies

Check if policies are applied correctly:

# Check system policies
ls -la /etc/brave/policies/managed/

# Verify policy content
cat /etc/brave/policies/managed/privacy-policy.json | jq .

# Check user preferences
cat ~/.config/BraveSoftware/Brave-Browser/Default/Preferences | jq .

Test Configuration

# Test with specific configuration
brave-browser --user-data-dir=/tmp/brave-test --no-first-run

🔧 Troubleshooting Configuration

Reset to Defaults

# Reset system policies
sudo rm -rf /etc/brave/policies/

# Reset user settings
rm -rf ~/.config/BraveSoftware/

# Rerun BravePurifier
sudo ./brave-purifier.sh

Debug Configuration Issues

# Check policy application
brave-browser --show-component-extension-options

# Verify settings
brave-browser chrome://policy/
brave-browser chrome://settings/

For more troubleshooting help, see Troubleshooting page.

Debloat Configuration

Brave Purifier now uses grouped debloat options for easier configuration:

  • Brave Features & Services: Rewards, Wallet, VPN, News, Talk, Sync, pings, analytics, crypto, web3, etc.
  • Privacy & Tracking: Telemetry, Safe Browsing, Metrics, Log Upload, Heartbeat
  • Autofill & Passwords: Autofill, Password Manager
  • Permissions: Camera, Microphone, Location, Notifications, Sensors, Popups, WebUSB, WebBluetooth, Serial, HID, FileSystem, etc.
  • Other UI & Suggestions: Spellcheck, Home Button, Import Passwords, Import Search Engine

Prompted separately:

  • Search Suggestions
  • Web Store
  • Background Mode

Reset to Defaults:

  • At the start, you can choose to reset all Brave settings to defaults (does NOT delete bookmarks, passwords, cookies, credentials, autofill, or sync data).

Search Engine:

  • At the end, you can choose to set Google as the default search engine, or keep it unchanged.

When running the script, you will be prompted for each group and these individual options. Answer 'y' to debloat all features in that group/option, or 'n' to skip.

Example:

Brave Features & Services (Rewards, Wallet, VPN, News, Talk, Sync, pings, analytics, crypto, web3, etc.)
  Disables all Brave-specific services, crypto, rewards, wallet, and telemetry.
Debloat this group? [Y/n]: y

Privacy & Tracking (Telemetry, Safe Browsing, Metrics, Log Upload, Heartbeat)
  Disables all tracking, telemetry, and privacy-invasive features.
Debloat this group? [Y/n]: y

Autofill & Passwords (Autofill, Password Manager)
  Disables autofill and password manager features.
Debloat this group? [Y/n]: n

Permissions (Camera, Microphone, Location, Notifications, Sensors, Popups, WebUSB, WebBluetooth, Serial, HID, FileSystem, etc.)
  Blocks access to sensitive device features and permissions.
Debloat this group? [Y/n]: y

Other UI & Suggestions (Spellcheck, Home Button, Import Passwords, Import Search Engine)
  Disables UI suggestions and import features.
Debloat this group? [Y/n]: n

Search Suggestions (address bar autocomplete, etc.)
  Disables search suggestions in the address bar.
Debloat this option? [Y/n]: y

Web Store (extension/add-on store visibility)
  Hides the web store icon and blocks extension installs.
Debloat this option? [Y/n]: y

Background Mode (Brave running in background)
  Prevents Brave from running in the background.
Debloat this option? [Y/n]: y

Do you want to set Google as the default search engine? (Otherwise, it will remain unchanged) [y/N]: n

🚀 Cross-Platform Support

  • Linux: Full support for all major distributions.
  • Windows: Support coming soon! Windows compatibility is a work in progress and will be available in a future release.
Add a custom footer
Add a custom sidebar

Clone this wiki locally