# Proxy - System HTTP/HTTPS Proxy

> Configure a system proxy server in VyOS to manage internet connectivity, package updates, and system image downloads through a central gateway.

Source: https://opennix.org/en/docs/vyos/system/vyos-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

```bash
set system proxy url <proxy-url>
```

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

**Example:**

```bash
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:

```bash
set system proxy port <port-number>
```

**Parameters:**
- `<port-number>`: Port number (1-65535)

**Example:**

```bash
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

```bash
set system proxy username <username>
```

**Parameters:**
- `<username>`: Username for authentication

#### Setting the password

```bash
set system proxy password <password>
```

**Parameters:**
- `<password>`: Password for authentication

**Full configuration example with authentication:**

```bash
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.

```bash
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:**

```bash
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.

```bash
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:**

```bash
# 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:**

```bash
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.

```bash
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:**

```bash
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.

```bash
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`:

```bash
#!/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.

```bash
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

```bash
show system proxy
```

**Example output:**

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

### Checking the environment variables

```bash
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

```bash
curl -I http://example.com
```

#### Checking an HTTPS connection

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

#### Detailed diagnostics with curl

```bash
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

```bash
# 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

```bash
configure
show system proxy
```

### Viewing in JSON format

```bash
show configuration json | jq '.system.proxy'
```

**Example output:**

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

### Exporting the proxy configuration

```bash
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:**

```bash
# 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:**

```bash
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:**

```bash
# 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:**

```bash
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:**

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

# Check the environment variables
env | grep -i proxy
```

**Temporary workaround for testing:**

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

**Permanent solution:**

Add the proxy certificate to the trusted store:

```bash
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:

```bash
#!/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`:

```bash
#!/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:

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

## Best practices

### 1. Credential security

**Not recommended:**
```bash
set system proxy password 'password123'
```

**Recommended:**
- Use strong passwords
- Rotate credentials regularly
- Use separate accounts for each router
- Limit the privileges of proxy accounts

```bash
set system proxy username vyos-router-01
set system proxy password 'C0mpl3x!P@ssw0rd#2024'
```

### 2. Documenting the configuration

Add comments to the configuration:

```bash
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`:

```bash
#!/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:

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

Set up a periodic check through the task scheduler:

```bash
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`:

```bash
#!/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:

```bash
# 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:

```bash
# 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`:

```bash
#!/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:

```bash
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:

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

### Container (Podman) configuration

Containers may require separate proxy configuration:

```bash
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:

```bash
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

```bash
# 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:

```bash
configure

# Delete the entire proxy configuration
delete system proxy

commit
save
exit
```

**Verification:**

```bash
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

- [VyOS System Proxy Documentation](https://docs.vyos.io/en/latest/configuration/system/proxy.html)
- [VyOS System Configuration Guide](https://docs.vyos.io/en/latest/configuration/system/index.html)

### RFC standards

- [RFC 7617 - HTTP Basic Authentication](https://tools.ietf.org/html/rfc7617)
- [RFC 3986 - URI Generic Syntax](https://tools.ietf.org/html/rfc3986)

### Related documentation sections

- [System Login](/docs/vyos/system/vyos-login/) - User management and authentication
- [System Syslog](/docs/vyos/system/vyos-syslog/) - Logging of system events
- [Task Scheduler](/docs/vyos/system/vyos-task-scheduler/) - Task automation

## 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.