g3proxy

• Search for G3 Proxy in the Azure Marketplace, select the SecureAnyCloud publisher and choose Create.
• Select your subscription, resource group and region, and choose the recommended VM size.
• Provide your SSH public key for the azureuser administrative account.
• Configure the Network Security Group to allow inbound TCP 22 for administration from your address. Leave proxy port 3128 closed for now. You can open it later for your own clients if you need direct access.
• Review and create the virtual machine, then note its public IP address.

Deploy the image from the command line. Replace the subscription ID, image version and networking values with your own:

RG="proxy-prod"; LOCATION="eastus"; VM_NAME="proxy1" IMAGE_URN="sac1647283583153:g3proxy-ubuntu-24-04:default:latest" SSH_KEY="$(cat ~/.ssh/id_rsa.pub)" az group create --name "$RG" --location "$LOCATION"
# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:g3proxy-ubuntu-24-04:default:latest
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$IMAGE_URN" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 22 --priority 1001

Connect over SSH as the azureuser administrative account. Use the private key that matches the public key you supplied at deploy time:

ssh -i ~/.ssh/id_rsa azureuser@<public-ip>

The per-instance proxy username and password are generated on first boot and written to a root-only file. Read them with sudo:

sudo cat /root/g3proxy-credentials.txt

The file contains the PROXY_USERNAME and PROXY_PASSWORD values that are unique to this virtual machine, along with the proxy endpoint and usage examples. Keep these credentials safe. They are the only way to authenticate to the proxy.

Check that the service is active, confirm the version, and confirm that it is listening on port 3128 as the unprivileged g3proxy user:

systemctl is-active g3proxy.service /usr/local/bin/g3proxy --version sudo ss -tlnp | grep 3128 ps -o user=,comm= -C g3proxy

You should see active, the g3proxy version, a listener on *:3128, and the process owned by the g3proxy account rather than root.

The proxy is not an open relay. An anonymous request and a wrong-credential request are both refused with HTTP 407, while your per-instance credentials succeed over both HTTP and HTTPS.

On the virtual machine, read the username and password from the root-only credentials file into shell variables, so the secret is never typed on the command line. Pass them to curl:

U=$(sudo grep '^PROXY_USERNAME=' /root/g3proxy-credentials.txt | cut -d= -f2-)
P=$(sudo grep '^PROXY_PASSWORD=' /root/g3proxy-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'anonymous -> HTTP %{http_code}\n' -x http://127.0.0.1:3128 http://example.com
curl -s -o /dev/null -w 'wrong password -> HTTP %{http_code}\n' -x "http://$U:wrongpassword@127.0.0.1:3128" http://example.com
curl -s -o /dev/null -w 'authenticated HTTP -> HTTP %{http_code}\n' -x "http://$U:$P@127.0.0.1:3128" http://example.com
curl -s -o /dev/null -w 'authenticated HTTPS -> HTTP %{http_code}\n' -x "http://$U:$P@127.0.0.1:3128" https://example.com

The anonymous and wrong-password requests return HTTP 407, which confirms that no request is forwarded without valid credentials.

The two authenticated requests return HTTP 200. The HTTP request is forwarded directly, and the HTTPS request is tunneled with the CONNECT method to the TLS origin on port 443. From a remote client (see the next step), use the same username and password with your HTTP client's proxy setting.

The proxy port is not exposed by the recommended Network Security Group. The simplest way to use the proxy from your workstation is an SSH tunnel that forwards a local port to port 3128 on the virtual machine:

ssh -i ~/.ssh/id_rsa -L 3128:127.0.0.1:3128 azureuser@<public-ip>

With that tunnel open, point any client at http://127.0.0.1:3128 on your workstation and authenticate with the per-instance username and password. For example, set the https_proxy environment variable to http://PROXY_USERNAME:PROXY_PASSWORD@127.0.0.1:3128 and run your HTTP client.

If you prefer to reach the proxy directly rather than over a tunnel, do both of the following:

• Add an inbound rule to the virtual machine's Network Security Group allowing TCP 3128 from your own client source range only:

az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 3128 --priority 1002 \
  --source-address-prefixes <your-mgmt-cidr>

• Widen the proxy's ingress access list to include that range. Edit /etc/g3proxy/default/main.yml, add your CIDR under server -> ingress_network_filter -> allow, validate the configuration, and reload the service:

sudo /usr/local/bin/g3proxy -t -c /etc/g3proxy/default/main.yml
sudo systemctl reload g3proxy

Keep both the Network Security Group rule and the ingress access list scoped to the smallest client range you need. The default policy accepts loopback and private ranges only, and destinations are limited to the standard web ports (80, 443 and 563), so the proxy cannot be abused to tunnel to arbitrary services.

The shipped configuration is secure by default. You can review its security sections at any time:

sudo sed -n '21,72p' /etc/g3proxy/default/main.yml

Key controls in the configuration:

• Authentication required. A user_group is attached to the HTTP proxy server, so every request must present valid per-instance credentials.
• Ingress access list. Authenticated clients are accepted from loopback and private (RFC1918) ranges only, with a deny-by-default policy.
• Destination port filter. Only HTTP (80), HTTPS (443) and NNTPS (563) destinations are permitted, so the proxy cannot tunnel to SMTP, SSH or other arbitrary ports.
• Anti-SSRF egress filter. The proxy denies the cloud metadata and link-local range (169.254.0.0/16) and loopback on egress, so it cannot be used to reach instance metadata or local-only services.

The credentials are also stored safely. The plaintext file is root-only (mode 0600), and the proxy's own dynamic users file stores a crypt hash of the per-instance password rather than the plaintext. That file is readable only by root and the g3proxy group.

The proxy runs under systemd. Common operations:

systemctl status g3proxy.service --no-pager sudo systemctl restart g3proxy.service
sudo journalctl -u g3proxy.service --no-pager -n 50

After editing the configuration, validate it before reloading:

sudo /usr/local/bin/g3proxy -t -c /etc/g3proxy/default/main.yml

• Open the product page on AWS Marketplace and choose Continue to Subscribe, then Continue to Configuration.
• Select the software version and your AWS Region, then choose Continue to Launch.
• Under Choose Action, select Launch through EC2. Pick an instance type (a general-purpose m5.large is a good starting point), your key pair, and a security group that allows inbound SSH (port 22).
• Launch the instance and note its public IP address or DNS name.

Launch the subscribed image from the command line. Replace the AMI ID, key name, security group and subnet with your own:

aws ec2 run-instances \
  --image-id ami-0123456789abcdef0 \
  --instance-type m5.large \
  --key-name my-key \
  --security-group-ids sg-0123456789abcdef0 \
  --subnet-id subnet-0123456789abcdef0 \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=g3proxy}]'

Connect over SSH with the private key for the key pair you launched with. The login user depends on the OS variant. For Ubuntu 24.04, the login user is ubuntu.

ssh -i /path/to/my-key.pem ubuntu@<public-ip>

The per-instance proxy username and password are generated on first boot and written to a root-only file. Read them with sudo:

sudo cat /root/g3proxy-credentials.txt

The file contains the PROXY_USERNAME and PROXY_PASSWORD values that are unique to this instance, along with the proxy endpoint and usage examples. Keep these credentials safe. They are the only way to authenticate to the proxy.

Check that the service is active, confirm the version, and confirm that it is listening on port 3128 as the unprivileged g3proxy user:

systemctl is-active g3proxy.service /usr/local/bin/g3proxy --version sudo ss -tlnp | grep 3128

You should see active, the g3proxy version, and a listener on *:3128 owned by the g3proxy process.

An anonymous request through the proxy must be refused with HTTP 407 Proxy Authentication Required:

curl -s -o /dev/null -w 'anonymous -> HTTP %{http_code}\n' -x http://127.0.0.1:3128 http://example.com

This confirms that the proxy is not an open relay. Without valid credentials, no request is forwarded.

Use your per-instance credentials to send an HTTP request and an HTTPS request through the proxy. On the instance, read the username and password from the root-only credentials file into shell variables, so the secret is never typed on the command line. Pass them to curl:

U=$(sudo grep '^PROXY_USERNAME=' /root/g3proxy-credentials.txt | cut -d= -f2-)
P=$(sudo grep '^PROXY_PASSWORD=' /root/g3proxy-credentials.txt | cut -d= -f2-)
curl -s -o /dev/null -w 'authenticated HTTP -> HTTP %{http_code}\n' -x "http://$U:$P@127.0.0.1:3128" http://example.com
curl -s -o /dev/null -w 'authenticated HTTPS -> HTTP %{http_code}\n' -x "http://$U:$P@127.0.0.1:3128" https://example.com

Both requests return HTTP 200. The HTTP request is forwarded directly, and the HTTPS request is tunneled with the CONNECT method to the TLS origin on port 443. From a remote client (see the next step), use the same username and password with your HTTP client's proxy setting.

The proxy port is not exposed by the recommended security group. The simplest way to use the proxy from your workstation is an SSH tunnel that forwards a local port to port 3128 on the instance:

ssh -i /path/to/my-key.pem -L 3128:127.0.0.1:3128 ubuntu@<public-ip>

With that tunnel open, point any client at http://127.0.0.1:3128 on your workstation and authenticate with the per-instance username and password. For example, set the https_proxy environment variable to http://PROXY_USERNAME:PROXY_PASSWORD@127.0.0.1:3128 and run your HTTP client.

If you prefer to reach the proxy directly rather than over a tunnel, do both of the following:

• Add an inbound rule to the instance's security group allowing TCP 3128 from your own client source range only.

• Widen the proxy's ingress access list to include that range. Edit /etc/g3proxy/default/main.yml and add your CIDR under server -> ingress_network_filter -> allow, then reload the service:

sudo systemctl reload g3proxy

Keep both the security group rule and the ingress access list scoped to the smallest client range you need. The default policy accepts loopback and private ranges only, and destinations are limited to the standard web ports (80, 443 and 563), so the proxy cannot be abused to tunnel to arbitrary services.

The shipped configuration is secure by default. You can review it at any time:

sudo sed -n '1,80p' /etc/g3proxy/default/main.yml

Key controls in the configuration:

• Authentication required. A user_group is attached to the HTTP proxy server, so every request must present valid per-instance credentials.
• Ingress access list. Authenticated clients are accepted from loopback and private (RFC1918) ranges only, with a deny-by-default policy.
• Destination port filter. Only HTTP (80), HTTPS (443) and NNTPS (563) destinations are permitted, so the proxy cannot tunnel to SMTP, SSH or other arbitrary ports.
• Anti-SSRF egress filter. The proxy denies the cloud metadata and link-local range (169.254.0.0/16) and loopback on egress, so it cannot be used to reach instance metadata or local-only services.

The proxy runs under systemd. Common operations:

systemctl status g3proxy.service --no-pager sudo systemctl restart g3proxy.service
sudo journalctl -u g3proxy.service --no-pager -n 50

After editing the configuration, validate it before reloading:

sudo /usr/local/bin/g3proxy -t -c /etc/g3proxy/default/main.yml