Skip to content

Latest commit

 

History

History
277 lines (195 loc) · 6.8 KB

go-camo.1.adoc

File metadata and controls

277 lines (195 loc) · 6.8 KB
Raw

go-camo(1)

NAME

go-camo - Go version of Camo server

SYNOPSIS

go-camo [OPTION [OPTION-ARGUMENT]]…​

DESCRIPTION

go-camo(1) is an implementation of Camo in Go.

Camo is a special type of image proxy that proxies non-secure images over SSL/TLS. This prevents mixed content warnings on secure pages.

It works in conjunction with back-end code to rewrite image URLs and sign them with an HMAC.

ENVIRONMENT VARS

GOCAMO_HMAC

The HMAC key to use.

HTTPS_PROXY

Configure an outbound proxy. Either a complete URL or a host[:port], in which case the http scheme is assumed.

It will be used as the proxy URL for HTTPS requests.

HTTP_PROXY

Configure an outbound proxy. Either a complete URL or a host[:port], in which case the http scheme is assumed.

It will be used as the proxy URL for HTTP requests.

Note
On Environmen Vars vs OPTIONS precedence

OPTIONS, if provided, override those defined in environment variables.

For exmaple, if the HMAC key is provided on the command line, it will override (if present), an HMAC key set in the environment var.

OPTIONS

-k, --key=<HMAC_KEY>

The HMAC key to use.

-H, --header=<HEADER>

Add additional header to each response. This option can be used multiple times to add multiple headers. When specified, these headers are set unconditionally on all responses.

See ADD_HEADERS for more info.

--listen=<ADDRESS:PORT>

Address and port to listen to, as a string of ADDRESS:PORT.
Default: 0.0.0.0:8080

--socket-listen=<SOCKET_PATH>

Path for unix domain socket to bind to for HTTP.

--ssl-listen=<ADDRESS:PORT>

Address and port to listen via SSL to, as a string of ADDRESS:PORT.

--ssl-key=<SSL-KEY-FILE>

Path to ssl private key.
Default: key.pem

--ssl-cert=<SSL-CERT-FILE>

Path to ssl certificate.
Default: cert.pem

--quic

Enable http3/quic. Binds to the same port number as --ssl-listen but udp+quic.

--automaxprocs

Set GOMAXPROCS automatically to match Linux container CPU quota/limits.

--max-size=<SIZE>

Max response size allowed in KB. Set to 0 to disable size restriction.
Default: 0

--timeout=<TIME>

Timeout value for upstream response. Format is "4s" where s means seconds.
Default: 4s

--max-redirects

Maximum number of redirects to follow.
Default: 3

--metrics

Enable Prometheus compatible metrics endpoint.

If the metrics flag is provided, then the service will expose a Prometheus /metrics endpoint and a /debug/vars endpoint from the go expvar package.

See METRICS for more info.

--no-debug-vars

If the no-debug-vars flag is provided along with the metrics flag, the /debug/vars endpoint is removed.

See METRICS for more info.

--no-log-ts

Do not add a timestamp to logging output.

--no-fk

Disable frontend http keep-alive support.

--no-bk

Disable backend http keep-alive support.

--log-json

Log in JSON format.

--allow-content-video

Additionally allow video/* content type.

--allow-content-audio

Additionally allow audio/* content type.

--allow-credential-urls

Allow urls to contain user/pass credentials.

--filter-ruleset=<FILE>

Path to a text file that contains a list (one per line) filter rules.

If an filter-ruleset file is defined, that file is read and each line converted into a filter rule. If the request fails the rule-set, the request is denied.

See go-camo-filtering(5) for more information.

--server-name=<SERVER-NAME>

Value to use for the HTTP server field.
Default: go-camo

--expose-server-version

Include the server version in the HTTP server response header.

--enable-xfwd4

Enable x-forwarded-for passthrough/generation.

-v, --verbose

Show verbose (debug) level log output

-V, --version

Print version and exit; specify twice to show license information.

-h, --help

Show help output and exit.

ADD_HEADERS

Additional default headers (headers sent on every reply) can be set with the -H, --header flag. This option can be used multiple times.

The list of default headers sent are:

X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'none'

Additional headers are added to the above set.

As an example, if you wanted to return an Strict-Transport-Security and an X-Frame-Options header by default, you could add this to the command line:

go-camo -k BEEFBEEFBEEF \
    -H "Strict-Transport-Security: max-age=16070400" \
    -H "X-Frame-Options: deny"

METRICS

When the --metrics flag is used, the service will expose a Prometheus-compatible /metrics endpoint. This can be used by monitoring systems to gather data.

The endpoint includes all of the default go_ and process_. In addition, a number of custom metrics.

A /debug/vars endpoint is also included with --metrics by default. This endpoint returns memstats and some additional data. This endpoint can be disabled by additionally supplying the --no-debug-vars flag.

Table 1. Exposed Camo Metrics
Metric Type Description

camo_response_duration_seconds

Histogram

A histogram of latencies for proxy responses.

camo_response_size_bytes

Histogram

A histogram of sizes for proxy responses.

camo_proxy_content_length_exceeded_total

Counter

The number of requests where the content length was exceeded.

camo_proxy_reponses_failed_total

Counter

The number of responses that failed to send to the client.

camo_proxy_reponses_truncated_total

Counter

The number of responess that were too large to send.

camo_responses_total

Counter

Total HTTP requests processed by the go-camo, excluding scrapes.

It also includes a camo_build_info metric that exposes the version. In addition, you can expose some extra data to metrics via env vars, if desired:

  • Revision via APP_INFO_REVISION

  • Branch via APP_INFO_BRANCH

  • BuildDate via APP_INFO_BUILD_DATE

  • You can also override the version by setting APP_INFO_VERSION

EXAMPLES

Listen on loopback port 8080 with a upstream timeout of 6 seconds:

go-camo -k BEEFBEEFBEEF \
    --listen=127.0.0.1:8080 \
    --timeout=6s

Set HMAC key via env var, and an HSTS header:

export GOCAMO_HMAC=BEEFBEEFBEEF
go-camo \
    --listen=127.0.0.1:8080 \
    --timeout=6s \
    -H "Strict-Transport-Security: max-age=16070400"