Language Configuration
Some language-specific environment configuration may be necessary but you should not need to modify your application code to use proxymock.
Configuring the Proxy
As the name implies, proxymock is a proxy which works by routing traffic from your application through proxymock before it goes to the final destination.
99% of the time proxy configuration does not require a code change, but some HTTP client libraries have their own proxy configuration that may override or ignore environment variables. Check the documentation for your specific library.
Record inbound traffic by setting the --app-port
flag and making requests to port 4143
instead of your application's port.
- Go
- Java
- Python
- Node.js
- Ruby
- PHP
- C#/.NET
- Rust
Go respects proxy environment variables.
export HTTP_PROXY=http://localhost:4140
export HTTPS_PROXY=http://localhost:4140
export NO_PROXY=localhost,127.0.0.1
Use the SOCKS proxy to capture database traffic:
export ALL_PROXY=socks5://localhost:4140
Java supports -D
flags to set system properties, which can be set in an environment variable.
export JAVA_TOOL_OPTIONS="-Dhttp.proxyHost=localhost -Dhttp.proxyPort=4140 -Dhttps.proxyHost=localhost -Dhttps.proxyPort=4140"
Use the SOCKS proxy to capture database traffic:
export JAVA_TOOL_OPTIONS="-DsocksProxyHost=localhost -DsocksProxyPort=4140"
With authentication and TLS certificates:
export JAVA_TOOL_OPTIONS="-Dhttp.proxyHost=localhost -Dhttp.proxyPort=4140 -Dhttps.proxyHost=localhost -Dhttps.proxyPort=4140 -Djavax.net.ssl.trustStore=$HOME/.speedscale/certs/cacerts.jks -Djavax.net.ssl.trustStorePassword=changeit"
Bypass proxy for specific hosts:
-Dhttp.nonProxyHosts="localhost|127.0.0.1|*.internal.domain"
These options include the -D
flags for TLS. See the Decrypting-TLS section below.
Python respects proxy environment variables.
export HTTP_PROXY=http://localhost:4140
export HTTPS_PROXY=http://localhost:4140
export NO_PROXY=localhost,127.0.0.1
Use the SOCKS proxy to capture database traffic (requires PySocks
package):
export ALL_PROXY=socks5://localhost:4140
Node.js HTTP libraries handle proxies differently. Environment variables are NOT automatically used by most libraries.
For axios (requires explicit configuration or https-proxy-agent
):
const axios = require('axios');
// Option 1: Direct configuration
axios.get('https://example.com', {
proxy: {
protocol: 'http',
host: 'localhost',
port: 4140
}
});
// Option 2: Using https-proxy-agent
const HttpsProxyAgent = require('https-proxy-agent');
const agent = new HttpsProxyAgent('http://localhost:4140');
axios.get('https://example.com', {
httpsAgent: agent
});
To respect environment variables with axios:
export HTTP_PROXY=http://localhost:4140
export HTTPS_PROXY=http://localhost:4140
Then use a library like https-proxy-agent
to read them.
Use the SOCKS proxy to capture database traffic (requires socks-proxy-agent
):
const SocksProxyAgent = require('socks-proxy-agent');
const agent = new SocksProxyAgent('socks5://localhost:4140');
Ruby's Net::HTTP
does not automatically use proxy environment variables by default, but :ENV
can be passed to Net::HTTP.new
:
export http_proxy=http://localhost:4140
export https_proxy=http://localhost:4140
export no_proxy=localhost,127.0.0.1
require 'net/http'
# This will use environment variables
Net::HTTP.new('example.com', nil, :ENV).start do |http|
# Uses proxy from env vars if set
end
# Or with URI
uri = URI('https://example.com')
Net::HTTP.start(uri.host, uri.port, :p_addr => :ENV) do |http|
# Uses proxy from env vars if set
end
PHP does not automatically use environment variables so it must be set explicitly. There multiple ways to configure proxies depending on the method used.
Using cURL:
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://example.com");
curl_setopt($ch, CURLOPT_PROXY, "http://localhost:4140");
// For SOCKS proxy
// curl_setopt($ch, CURLOPT_PROXY, "socks5://localhost:4140");
// With authentication
curl_setopt($ch, CURLOPT_PROXYUSERPWD, "username:password");
$response = curl_exec($ch);
curl_close($ch);
Using stream context:
$context = stream_context_create([
'http' => [
'proxy' => 'tcp://localhost:4140',
'request_fulluri' => true,
],
'ssl' => [
'verify_peer' => false, // Only for testing
]
]);
$response = file_get_contents('https://example.com', false, $context);
Set default proxy for all stream operations:
stream_context_set_default([
'http' => ['proxy' => 'tcp://localhost:4140']
]);
.NET Core/5+ respects proxy environment variables:
export HTTP_PROXY=http://localhost:4140
export HTTPS_PROXY=http://localhost:4140
export NO_PROXY=localhost,127.0.0.1
Rust with the reqwest
crate respects proxy environment variables by default:
export HTTP_PROXY=http://localhost:4140
export HTTPS_PROXY=http://localhost:4140
export NO_PROXY=localhost,127.0.0.1
Use the SOCKS proxy to capture database traffic (requires socks feature in Cargo.toml):
export ALL_PROXY=socks5://localhost:4140
Then modify Cargo.toml to:
reqwest = { version = "your_version_here", features = ["socks"] }
Decrypting TLS
proxymock attempts to automatically configure TLS on the desktop so manual configuration is only necessary in special environments like CI/CD or when TLS decryption does not work out of the box.
Commands and flags should be run in the environment where your application is running.
- Go
- Node.js
- Ruby
- .NET
- Java
- C++
- Python
export SSL_CERT_FILE="${HOME}/.speedscale/certs/tls.crt"
Go applications using OpenSSL will respect the SSL_CERT_FILE
environment variable to locate trusted root certificates. This environment variable will be automatically populated by the Speedscale operator.
export NODE_EXTRA_CA_CERTS="${HOME}/.speedscale/certs/tls.crt"
For Node.js applications newer than v7.3.0
.
export SSL_CERT_FILE="${HOME}/.speedscale/certs/tls.crt"
Ruby applications using OpenSSL will respect the SSL_CERT_FILE
environment variable to locate trusted root certificates. This environment variable will be automatically populated by the Speedscale operator.
export SSL_CERT_FILE="${HOME}/.speedscale/certs/tls.crt"
.NET Core uses OpenSSL on Linux and Mac which respects default settings. The default Microsoft .NET Docker base images are Linux based which means these settings apply, however running Windows based workloads may require additional configuration.
Java applications utilize a truststore to specify certificates to be trusted.
On desktop:
Create the keystore with Speedscale certs.
proxymock certs --jks
Then apply these flags when running your app:
java \
-Djavax.net.ssl.trustStore=/etc/ssl/speedscale/jks/cacerts.jks \
-Djavax.net.ssl.trustStorePassword=changeit \
-jar app.jar
In cluster:
During Operator installation a secret called speedscale-jks
will be created that contains the speedscale-certs
root CA
along with a standard set of CA certs used by openjdk
. This secret is automatically mounted when the
tls-out
setting is configured as shown below. The Java app itself needs to be configured to use this secret
as well which requires configuring your JVM to use the truststore with these settings:
These can be automatically applied by adding to your JVM by setting JAVA_TOOL_OPTIONS
. This can be set
on your workload by adding the sidecar.speedscale.com/tls-java-tool-options: "true"
annotation. Read more
about this setting here.
When running in-cluster, these flags are also surfaced as an environment variable SPEEDSCALE_JAVA_OPTS
if you need to merge with your own existing sets of Java flags.
apiVersion: apps/v1
kind: Deployment
metadata:
name: spring-boot-app
annotations:
sidecar.speedscale.com/inject: "true"
sidecar.speedscale.com/tls-out: "true"
sidecar.speedscale.com/tls-java-tool-options: "true"
export SSL_CERT_FILE="${HOME}/.speedscale/certs/tls.crt"
C++ applications using OpenSSL will respect the SSL_CERT_FILE
environment variable to locate trusted root certificates. This environment variable will be automatically populated by the Speedscale operator.
export REQUESTS_CA_BUNDLE="${HOME}/.speedscale/certs/tls.crt"
Python applications (including the popular requests library and many others) will use the REQUESTS_CA_BUNDLE
environment variable to locate trusted root certificates.