Additional environment vars are show as part of the --help output.

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

=== Command line flags

[source,text] ---- $ go-camo -h Usage: go-camo [flags]

An image proxy that proxies non-secure images over SSL/TLS

Flags: -h, --help Show context-sensitive help. -v, --verbose Show verbose (debug) log level output ($GOCAMO_VERBOSE) -V, --version Print version and exit; specify twice to show license information.

Flags for general behavior -k, --key=STRING HMAC key ($GOCAMO_HMAC) --automaxprocs Set GOMAXPROCS automatically to match Linux container CPU quota/limits ($GOCAMO_AUTOMAXPROCS).

Flags for listeners --socket-listen=PATH Path for unix domain socket to bind to for HTTP ($GOCAMO_SOCKET_LISTEN) --listen="0.0.0.0:8080" Address:Port to bind to for HTTP ($GOCAMO_LISTEN) --ssl-listen=HOST_PORT Address:Port to bind to for HTTPS/SSL/TLS ($GOCAMO_SSL_LISTEN) --quic Enable http3/quic. Binds to the same port number as ssl-listen but udp+quic ($GOCAMO_QUIC). --ssl-key=PATH ssl private key (key.pem) path ($GOCAMO_SSL_KEY) --ssl-cert=PATH ssl cert (cert.pem) path ($GOCAMO_SSL_CERT)

Flags for proxy behavior --max-size=INT Max allowed response size, in KB ($GOCAMO_MAX_SIZE) --max-size-redirect=URL redirect to URL when max-size is exceeded ($GOCAMO_MAX_SIZE_REDIRECT) --max-redirects=3 Maximum number of redirects to follow ($GOCAMO_MAX_REDIRECTS) --xfwd4 Enable x-forwarded-for passthrough/generation ($GOCAMO_XFWD_FOR) --no-fk Disable frontend http keep-alive support (frontend) ($GOCAMO_NO_FK) --no-bk Disable backend http keep-alive support (backend) ($GOCAMO_NO_BK) --allow-content-video Additionally allow 'video/*' content ($GOCAMO_ALLOW_CONTENT_VIDEO) --allow-content-audio Additionally allow 'audio/*' content ($GOCAMO_ALLOW_CONTENT_AUDIO) --allow-credential-urls Allow urls to contain user/pass credentials ($GOCAMO_ALLOW_CREDENTIAL_URLS) --timeout=4s Upstream request timeout (backend) ($GOCAMO_TIMEOUT) --idletimeout=30s Maximum amount of time to wait for the next request when keep-alive is enabled (frontend) ($GOCAMO_IDLETIMEOUT) --readtimeout=30s Maximum duration for reading the entire request, including the body (frontend) ($GOCAMO_READTIMEOUT) --user-agent="go-camo" user-agent for outgoing requests ($GOCAMO_USER_AGENT) --filter-ruleset=PATH Text file containing filtering rules (one per line) ($GOCAMO_FILTER_RULESET)

Flags for responses -H, --header=HEADER,... Add additional header to each response. This option can be used multiple times to add multiple headers ($GOCAMO_HEADER). --server-name="go-camo" Value to use for the HTTP server field ($GOCAMO_SERVER_NAME) --expose-server-version Include the server version in the HTTP server response header ($GOCAMO_EXPOSE_SERVER_VERSION)

Flags for logging and metrics --metrics Enable Prometheus compatible metrics endpoint ($GOCAMO_METRICS) --no-debug-vars Disable the /debug/vars/ metrics endpoint. This option has no effects when the metrics are not enabled ($GOCAMO_NO_DEBUG_VARS). --no-log-ts Do not add a timestamp to logging ($GOCAMO_NO_LOG_TS) --log-json Log in JSON format ($GOCAMO_LOG_JSON) --prof Enable go http profiler endpoint ($GOCAMO_PROF) ----

A few notes about specific flags:

• --filter-ruleset

Regarding evaluation: The ruleset is NOT evaluated in-order. The rules process in two phases: "allow rule phase" where the allow rules are evaluated, and the "deny rule phase" where the deny rules are evaluated. First match in each phase "wins" that phase.

In the "allow phase", an origin request must match at least one allow rule. The first rule to match "wins" and the request moves on to the next phase. If there are no allow rules supplied, this phase is skipped.

In the deny rule phase, any rule that matches results in a rejection. The first match "wins" and the request is failed. If there are no deny rules supplied, this phase is skipped.

[NOTE] ==== It is always preferable to do filtering at the point of URL generation and signing. The filter-ruleset functionality (both allow and deny) is supplied predominantly as a fallback safety measure, for cases where you have previously generated a URL and you need a quick temporary fix, or where rolling keys takes a while and/or is difficult. ==== --

• --max-size

• --metrics

• --no-debug-vars

• -k, --key

• -H, --header

The list of default headers sent are:

[source,text] ---- X-Content-Type-Options: nosniff X-XSS-Protection: 1; mode=block Content-Security-Policy: default-src 'none'; img-src data:; style-src 'unsafe-inline' ----

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

[source,text] ---- -H "Strict-Transport-Security: max-age=16070400" ---- --

• --allow-content-video and --allow-content-audio

Add the --allow-content-video argument to addtionally allow video/* content types.

Add the --allow-content-audio argument to addtionally allow audio/* content types. --

== Upstream Http Proxying

Care should be taken when using upstream http proxy support. go-camo has several protections against SSRF vectors, for example:

• Checking http redirect chains against rfc1918 addresses.
• Limits to maximum number of redirects.
• Protection against self-redirect loops.
• Various other protections.

Some examples (list is not exhaustive):

• The upstream http proxy itself may be responsible for following redirects

• The upstream http proxy itself will be responsible for connecting to external

• There may be other chances for "configuration confusion" -- where two

Proper configuration of the upstream http proxy may mitigate these issues. + Test your configurations and monitor carefully!

== Monitoring

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

[%header%autowidth.stretch] |=== | Name | Type | Help

| 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 responses 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

== Additional tools

Go-Camo includes a couple of additional tools.

=== url-tool

The url-tool utility provides a simple way to generate signed URLs from the command line.

[source,text] ---- $ url-tool -h Usage: url-tool [OPTIONS]

Application Options: -k, --key= HMAC key -p, --prefix= Optional URL prefix used by encode output

Help Options: -h, --help Show this help message

Available commands: decode Decode a URL and print result encode Encode a URL and print result ----

Example usage:

[source,text] ----

hex

$ url-tool -k "test" decode "https://img.example.org/0f6def1cb147b0e84f39cbddc5ea10c80253a6f3/687474703a2f2f676f6c616e672e6f72672f646f632f676f706865722f66726f6e74706167652e706e67" http://golang.org/doc/gopher/frontpage.png

base64

$ url-tool -k "test" decode "https://img.example.org/D23vHLFHsOhPOcvdxeoQyAJTpvM/aHR0cDovL2dvbGFuZy5vcmcvZG9jL2dvcGhlci9mcm9udHBhZ2UucG5n" http://golang.org/doc/gopher/frontpage.png ----

== Containers

There are containers built automatically from version tags, pushed to both {link-docker-containers} and {link-github-containers}.

These containers are untested and provided only for those with specific containerization requirements. When in doubt, prefer the statically compiled {link-releases}, unless you specifically need a container.

== Changelog

See xref:CHANGELOG.md[CHANGELOG].

== Known Users and/or Recommendations

• https://docs.gitlab.com/security/asset_proxy/#installing-camo-server[Gitlab]
• https://zulip.readthedocs.io/en/stable/production/securing-your-zulip-server.html#:~:text=Zulip%20supports%20using%20the%20go%2Dcamo%20image%20proxy%20to%20proxy%20content%20like%20inline%20image%20previews%2C%20that%20can%20be%20inserted%20into%20the%20Zulip%20message%20feed%20by%20other%20users.%20This%20ensures%20that%20clients%20do%20not%20make%20requests%20to%20external%20servers%20to%20fetch%20images%2C%20improving%20privacy[Zulip]
• https://github.com/pypi/camo[Pypi]

Released under the {link-mit-license}. See xref:LICENSE.md[LICENSE] file for details.