Documentation
VyOS Documentation
VyOS System Configuration
Proxy - System HTTP/HTTPS Proxy

Proxy - System HTTP/HTTPS Proxy

System Proxy in VyOS

Overview

The system proxy server in VyOS lets you define a centralized access point for all outbound HTTP, HTTPS, and FTP connections initiated by the system. This is essential in enterprise environments where direct internet access is restricted by security policies.

Purpose

The proxy server configuration in VyOS is used for:

  • System updates: Downloading new VyOS images with the add system image command
  • Package installation: Accessing package repositories through the proxy
  • File downloads: System operations that require access to external resources
  • Centralized traffic management: A single control point for outbound connections
  • Corporate policy compliance: Enforced use of the corporate proxy

Use cases

The system proxy applies to the following scenarios:

  1. Corporate networks: Mandatory use of a corporate proxy server
  2. Isolated segments: DMZ zones with restricted internet access
  3. Cloud infrastructures: Yandex Cloud, VK Cloud with centralized traffic management
  4. Auditing and monitoring: Control over all outbound connections
  5. Caching: Optimized delivery of frequently used resources

How it works

When you configure the system proxy, VyOS:

  1. Sets the environment variables http_proxy, https_proxy, and ftp_proxy
  2. Applies the settings to all system processes
  3. Routes all HTTP/HTTPS/FTP connections through the proxy
  4. Supports authentication per RFC 7617 (Basic Authentication)
  5. Allows specific hosts to be excluded from proxying

Configuration

Basic proxy setup

Setting the proxy server URL

set system proxy url <proxy-url>

Parameters:

  • <proxy-url>: Proxy server URL (with the http:// or https:// scheme)

Example:

configure
set system proxy url http://proxy.example.com
commit
save

Setting a non-standard port

By default, port 80 is used for the HTTP proxy. To change the port:

set system proxy port <port-number>

Parameters:

  • <port-number>: Port number (1-65535)

Example:

configure
set system proxy url http://proxy.example.com
set system proxy port 8080
commit
save

Proxy server authentication

VyOS supports HTTP Basic authentication in accordance with RFC 7617.

Setting the username

set system proxy username <username>

Parameters:

  • <username>: Username for authentication

Setting the password

set system proxy password <password>

Parameters:

  • <password>: Password for authentication

Full configuration example with authentication:

configure
set system proxy url http://proxy.corp.local
set system proxy port 3128
set system proxy username admin
set system proxy password SecurePassword123
commit
save

Proxy exclusions (No-Proxy)

Some hosts or subnets may require a direct connection without going through the proxy.

Note: As of VyOS 1.4/1.5, there is no explicit no-proxy command in the standard configuration, but you can use environment variables directly through scripts or configure exclusions at the proxy server level.

Configuration examples

Example 1: Simple proxy without authentication

Scenario: An organization uses the proxy server proxy.company.ru on the standard port 8080.

configure

# Configure the proxy server
set system proxy url http://proxy.company.ru
set system proxy port 8080

# Apply the configuration
commit
save
exit

Result:

vyos@router:~$ env | grep -i proxy
http_proxy=http://proxy.company.ru:8080
https_proxy=http://proxy.company.ru:8080
ftp_proxy=http://proxy.company.ru:8080

Example 2: Yandex Cloud - Corporate proxy for updates

Scenario: VyOS in Yandex Cloud, with internet access only through a corporate proxy server that requires authentication.

configure

# Core proxy parameters
set system proxy url http://proxy.yandex-cloud.internal
set system proxy port 3128

# Authentication
set system proxy username yc-vyos-router
set system proxy password 'Yc!Pr0xy@2024'

# Apply the configuration
commit
save
exit

Verifying connectivity:

# Check the environment variables
vyos@yc-router:~$ env | grep -i proxy

# Test a download through the proxy
vyos@yc-router:~$ curl -I https://cloud.yandex.ru

Updating the VyOS image through the proxy:

add system image https://downloads.vyos.io/rolling/current/vyos-1.5-rolling-latest.iso

Example 3: VK Cloud - Proxy with authentication

Scenario: VyOS in VK Cloud (Mail.ru Cloud Solutions), a segmented network with a mandatory proxy.

configure

# Configure the VK Cloud proxy
set system proxy url http://proxy.vkcloud.local
set system proxy port 8888

# User authentication
set system proxy username vk-network-admin
set system proxy password 'VKCloud$ecure2024'

# Apply and save
commit
save
exit

Verifying the configuration:

show system proxy

Expected output:

proxy {
    port 8888
    url http://proxy.vkcloud.local
    username vk-network-admin
    password ****************
}

Example 4: Multi-tier infrastructure

Scenario: A DMZ segment with access through a corporate proxy and protocol-specific settings.

configure

# DMZ proxy server
set system proxy url http://dmz-proxy.corp.local
set system proxy port 8080

# Account for the DMZ router
set system proxy username dmz-vyos-01
set system proxy password 'DmZ!R0ut3r#2024'

commit
save
exit

Additional configuration through environment variables (in scripts):

Create the script /config/scripts/proxy-exceptions.sh:

#!/bin/bash
# Additional proxy settings

export no_proxy="localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,172.16.0.0/12,.local,.corp.local"
export NO_PROXY="$no_proxy"

Example 5: HTTPS proxy with SSL

Scenario: Using an HTTPS proxy server with an encrypted connection.

configure

# HTTPS proxy
set system proxy url https://secure-proxy.enterprise.com
set system proxy port 8443

# Authentication
set system proxy username enterprise-router
set system proxy password 'EnT3rpr!se#SSL'

commit
save
exit

Important: When the proxy server uses self-signed certificates, SSL verification issues may occur. In such cases, additional configuration to trust the certificate at the system level may be required.

Verifying the configuration

Viewing the current proxy settings

show system proxy

Example output:

proxy {
    port 8080
    url http://proxy.example.com
    username admin
    password ****************
}

Checking the environment variables

env | grep -i proxy

Expected output:

http_proxy=http://admin:SecurePassword123@proxy.example.com:8080
https_proxy=http://admin:SecurePassword123@proxy.example.com:8080
ftp_proxy=http://admin:SecurePassword123@proxy.example.com:8080

Testing connectivity through the proxy

Checking an HTTP connection

curl -I http://example.com

Checking an HTTPS connection

curl -I https://www.google.com

Detailed diagnostics with curl

curl -v -x http://proxy.example.com:8080 https://downloads.vyos.io

Parameters:

  • -v: Verbose output
  • -x: Explicitly specify the proxy server

Verifying that updates work

# Attempt to download a VyOS image
add system image https://downloads.vyos.io/rolling/current/vyos-1.5-rolling-latest.iso

If the proxy is configured correctly, the download will proceed through the specified proxy server.

Operational commands

Viewing the configuration in configuration mode

configure
show system proxy

Viewing in JSON format

show configuration json | jq '.system.proxy'

Example output:

{
  "port": "8080",
  "url": "http://proxy.example.com",
  "username": "admin"
}

Exporting the proxy configuration

show configuration commands | grep "system proxy"

Output:

set system proxy port '8080'
set system proxy url 'http://proxy.example.com'
set system proxy username 'admin'

Environment variables

VyOS automatically creates the following environment variables when the proxy is configured:

http_proxy

Used for HTTP connections.

Format:

http_proxy=http://[username:password@]proxy-url:port

https_proxy

Used for HTTPS connections.

Format:

https_proxy=http://[username:password@]proxy-url:port

Note: Even for HTTPS connections, the http:// scheme is often used for the proxy connection itself if the proxy does not require SSL.

ftp_proxy

Used for FTP connections.

Format:

ftp_proxy=http://[username:password@]proxy-url:port

no_proxy

A list of hosts and subnets that should not be proxied.

Format:

no_proxy=localhost,127.0.0.1,.local,10.0.0.0/8

Note: In the standard VyOS configuration, no_proxy must be configured manually through scripts.

Troubleshooting

Problem 1: The proxy is not applied

Symptoms:

  • Update commands do not work
  • Environment variables are not set

Solution:

# Check the configuration status
show system proxy

# Make sure the configuration is committed
configure
commit
save

# Restart the session
exit

Problem 2: Authentication error 407

Symptoms:

HTTP 407 Proxy Authentication Required

Solution:

configure

# Verify the credentials
show system proxy

# Update the password
set system proxy password 'NewPassword'
commit
save

Problem 3: Connection timeouts

Symptoms:

  • Long waits when attempting to connect
  • Timeout errors

Diagnostics:

# Check that the proxy server is reachable
ping proxy.example.com

# Check the proxy port
telnet proxy.example.com 8080

# Check network connectivity
traceroute proxy.example.com

Solution:

configure

# Make sure the URL and port are correct
set system proxy url http://proxy.example.com
set system proxy port 8080

# Check the route to the proxy
show ip route

commit
save

Problem 4: SSL/TLS errors with an HTTPS proxy

Symptoms:

SSL certificate problem: self signed certificate

Diagnostics:

# Check the proxy certificate
openssl s_client -connect proxy.example.com:8443

# Check the environment variables
env | grep -i proxy

Temporary workaround for testing:

# Disable SSL verification (for testing only!)
curl -k https://example.com

Permanent solution:

Add the proxy certificate to the trusted store:

configure

# Install the CA certificate
set pki ca proxy-ca certificate '<base64-encoded-cert>'

commit
save

Problem 5: Some services do not use the proxy

Symptoms:

  • System commands work through the proxy
  • Custom scripts ignore the proxy

Solution:

Make sure the scripts inherit the environment variables:

#!/bin/vbash
source /etc/profile.d/vyatta-environment.sh

# Explicitly set the proxy
export http_proxy="http://proxy.example.com:8080"
export https_proxy="http://proxy.example.com:8080"

# Your code

Problem 6: The proxy blocks internal resources

Symptoms:

  • Access to internal servers does not work
  • Internal DNS queries go through the proxy

Solution:

Configure exclusions through no_proxy:

Create the script /config/scripts/post-config.d/proxy-no-proxy.sh:

#!/bin/bash

# Proxy exclusions
export no_proxy="localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,172.16.0.0/12,.local,.internal"
export NO_PROXY="$no_proxy"

# Save to the profile
cat > /etc/profile.d/no-proxy.sh << EOF
export no_proxy="$no_proxy"
export NO_PROXY="$no_proxy"
EOF

Make the script executable:

chmod +x /config/scripts/post-config.d/proxy-no-proxy.sh

Best practices

1. Credential security

Not recommended:

set system proxy password 'password123'

Recommended:

  • Use strong passwords
  • Rotate credentials regularly
  • Use separate accounts for each router
  • Limit the privileges of proxy accounts
set system proxy username vyos-router-01
set system proxy password 'C0mpl3x!P@ssw0rd#2024'

2. Documenting the configuration

Add comments to the configuration:

configure
set system proxy url http://proxy.corp.local
set system proxy port 3128

# Store the information in the system description
set system host-name vyos-with-proxy
set system domain-name corp.local

commit comment "Configured corporate proxy for system updates"
save

3. Monitoring and logging

Create the monitoring script /config/scripts/check-proxy.sh:

#!/bin/bash

LOGFILE="/var/log/vyos/proxy-check.log"
PROXY_HOST="proxy.corp.local"
PROXY_PORT="8080"

# Logging function
log() {
    echo "[$(date +'%Y-%m-%d %H:%M:%S')] $1" >> $LOGFILE
}

# Check proxy availability
if timeout 5 bash -c "cat < /dev/null > /dev/tcp/$PROXY_HOST/$PROXY_PORT" 2>/dev/null; then
    log "SUCCESS: Proxy $PROXY_HOST:$PROXY_PORT is reachable"
    exit 0
else
    log "ERROR: Proxy $PROXY_HOST:$PROXY_PORT is unreachable"
    exit 1
fi

Make the script executable:

chmod +x /config/scripts/check-proxy.sh

Set up a periodic check through the task scheduler:

configure
set system task-scheduler task check-proxy interval 5m
set system task-scheduler task check-proxy executable path /config/scripts/check-proxy.sh
commit
save

4. Backup proxy server

For critical systems, prepare an alternative configuration:

Create the script /config/scripts/proxy-failover.sh:

#!/bin/vbash
source /opt/vyatta/etc/functions/script-template

PRIMARY_PROXY="proxy-primary.corp.local:8080"
SECONDARY_PROXY="proxy-backup.corp.local:8080"

# Check the primary proxy
if timeout 3 curl -s -o /dev/null -x http://$PRIMARY_PROXY http://connectivity-check.vyos.io; then
    echo "Primary proxy is working"
    configure
    set system proxy url http://proxy-primary.corp.local
    set system proxy port 8080
    commit
    exit 0
else
    echo "Primary proxy failed, switching to backup"
    configure
    set system proxy url http://proxy-backup.corp.local
    set system proxy port 8080
    commit
    save
fi

5. Testing after changes

After any changes to the proxy configuration:

# 1. Check the configuration
show system proxy

# 2. Check the environment variables
env | grep -i proxy

# 3. Test HTTP connection
curl -I http://connectivity-check.vyos.io

# 4. Test HTTPS connection
curl -I https://www.google.com

# 5. Try downloading a small file
curl -o /tmp/test.txt http://ipv4.download.thinkbroadband.com/5MB.zip

6. Routine maintenance

Create a routine maintenance checklist:

Weekly:

  • Review the proxy logs /var/log/vyos/proxy-check.log
  • Test proxy server availability

Monthly:

  • Update passwords (under a rotation policy)
  • Check VyOS versions and available updates

Quarterly:

  • Audit the proxy configuration
  • Test the failover procedure
  • Update the documentation

7. Exclusions for internal resources

Always configure exclusions for:

# Local addresses
localhost, 127.0.0.1, ::1

# RFC 1918 private networks
10.0.0.0/8
172.16.0.0/12
192.168.0.0/16

# Link-local
169.254.0.0/16

# Internal domains
.local, .internal, .corp, .lan

# Cloud metadata services
169.254.169.254 (AWS, Yandex Cloud, VK Cloud)

8. Integration with monitoring systems

Export metrics for Prometheus/Grafana:

Create /config/scripts/proxy-metrics.sh:

#!/bin/bash

METRICS_FILE="/var/lib/node_exporter/textfile_collector/proxy_status.prom"
PROXY_HOST="proxy.corp.local"
PROXY_PORT="8080"

# Check availability
if timeout 3 bash -c "cat < /dev/null > /dev/tcp/$PROXY_HOST/$PROXY_PORT" 2>/dev/null; then
    STATUS=1
else
    STATUS=0
fi

# Write the metrics
cat > $METRICS_FILE << EOF
# HELP vyos_proxy_status Proxy server availability (1 = up, 0 = down)
# TYPE vyos_proxy_status gauge
vyos_proxy_status{host="$PROXY_HOST",port="$PROXY_PORT"} $STATUS
EOF

Interaction with other components

Updating system images

When a proxy is configured, the add system image command automatically uses the proxy:

add system image https://downloads.vyos.io/rolling/current/vyos-1.5-rolling-latest.iso

Installing packages with apt

If you need to install additional packages:

# The proxy variables are inherited
sudo apt update
sudo apt install <package-name>

Container (Podman) configuration

Containers may require separate proxy configuration:

configure

# Example container configuration with a proxy
set container name myapp environment HTTP_PROXY value 'http://proxy.example.com:8080'
set container name myapp environment HTTPS_PROXY value 'http://proxy.example.com:8080'
set container name myapp environment NO_PROXY value 'localhost,127.0.0.1,.local'

commit
save

VPN and proxy

When using VPN tunnels, make sure that traffic to the proxy server does not go through the VPN:

configure

# Add a route to the proxy server through the main gateway
set protocols static route <proxy-network>/24 next-hop <gateway-ip>

commit
save

Security

Security recommendations

  1. Password encryption: Passwords are stored in encrypted form in the configuration
  2. Account isolation: Use separate accounts for different routers
  3. Privilege restriction: Proxy accounts should have the minimum necessary privileges
  4. Auditing: Log all connections through the proxy at the proxy server level
  5. Monitoring: Watch for anomalous activity

Protecting credentials

# After configuring the proxy with a password
configure
commit
save

# The password is encrypted in the configuration
show system proxy

Output:

proxy {
    password ****************
    port 8080
    url http://proxy.example.com
    username admin
}

Access logging

On the proxy server side, configure detailed logging for auditing:

Squid example:

access_log /var/log/squid/access.log squid
auth_param basic program /usr/lib/squid/basic_ncsa_auth /etc/squid/passwords
auth_param basic realm VyOS Proxy Authentication

Removing the proxy configuration

To completely remove the proxy settings:

configure

# Delete the entire proxy configuration
delete system proxy

commit
save
exit

Verification:

env | grep -i proxy

The output should be empty after the configuration is removed.

Version compatibility

VyOS 1.4 (Sagitta LTS)

Fully supported:

  • Basic proxy configuration
  • Authentication
  • Environment variables

VyOS 1.5 (Circinus/Current)

Fully supported:

  • All features from 1.4
  • Improved HTTPS proxy handling
  • Better integration with containers

Note: The configuration syntax is identical across versions.

References and resources

Official documentation

RFC standards

Related documentation sections

Conclusion

The system proxy in VyOS is an essential component for operating in corporate and cloud environments with restricted internet access. A properly configured proxy ensures:

  • The ability to update the system
  • Compliance with corporate security policies
  • Centralized management of outbound traffic
  • Auditing and monitoring of network activity

Follow the security recommendations and best practices to ensure reliable and secure operation of your VyOS-based network infrastructure.

Reviewed by OpenNix LLC · Last updated on
Option - System OptionssFlow