primal/athens
1
0
Fork 0
mirror of https://github.com/gomods/athens synced 2026-02-03 12:10:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Adding docs for setting the GONOSUMDB env var on the Athens side (#1504)

Browse Source 
* Adding docs for setting the GONOSUMDB env var on the Athens side

Ref https://github.com/gomods/athens/issues/1363

* Updating with multiple repos, and adding a note

* Update docs/content/configuration/sumdb.md

Co-Authored-By: Ted Wexler <ted@stuckinacan.com>

* Qualifying "user"

Co-authored-by: Ted Wexler <ted@stuckinacan.com>
This commit is contained in:
Aaron Schlesinger
2020-02-19 16:52:24 -08:00
committed by GitHub
parent d7db2d4f11
commit ed703ee63d
1 changed files with 21 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/content/configuration/sumdb.md
+18 -12
View File
@@ -5,9 +5,10 @@ weight: 4
---
## Proxying A Checksum DB
The Athens Proxy has the ability to proxy a Checksum Database as defined by [this proposal](https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md) by the Go team.
Athens by default will accept proxying `https://sum.golang.org`. However, if you'd like to override that behavior or proxy more Checksum DBs you can do so through the `SumDBs` config or its equivalent Environment Variable: `ATHENS_SUM_DBS`
Athens by default will accept proxying `https://sum.golang.org`. However, if you'd like to override that behavior or proxy more Checksum DBs you can do so through the `SumDBs` config or its equivalent Environment Variable: `ATHENS_SUM_DBS`.
So for example, if you run the following command:
@@ -19,27 +20,32 @@ The Go command will proxy requests to `sum.golang.org` like this: `<athens-url>/
Note that as of this documentation (May 2019), you need to explicitly set `GOSUMDB=https://sum.golang.org`, but the Go team is planning on enabling this by default.
### Why a Checksum DB?
The reasons for needing a Checksum DB is explained in the linked proposal above. However, the reasons for proxying a Checksum DB are more explained below.
### Why Proxy a Checksum DB?
This is quite important. Say you are a company that is running an Athens instance, and you don't want the world to know about where your
repositories live. For example, say you have a private repo under `github.com/mycompany/secret-repo`. In order to ensure that the Go client
does not send a request to `https://sum.golang.org/lookup/github.com/mycompany/secret-repo@v1.0.0` and therefore leaking your private import path to the public, you need to ensure that you tell Go to skip particular import paths as such:
does not send a request to `https://sum.golang.org/lookup/github.com/mycompany/secret-repo@v1.0.0` and therefore leaking your private import path to the public, you need to ensure that you tell Go to skip particular import paths by setting the `GONOSUMDB` environment variable:
```
GONOSUMDB=github.com/mycompany/* go build
```
This will make sure that Go does not send any requests to the Checksum DB for your private import paths.
However, how can you ensure that all of your employees are building private code with the right configuration?
This will make sure that Go does not send any requests to the Checksum DB for your private import paths. However, how can you ensure that all of your employees are building private code with the right configuration?
Athens, in this case can help ensure that all private code flowing through it never goes to the Checksum DB. So as long as your employees are using Athens, then they will get a helpful reminder to ensure Their GONOSUMDB is rightly configured.
Athens, in this case can help ensure that all private code flowing through it is never checked against the checksum DB. That means that as long as your employees are using Athens, then they will get a helpful reminder to ensure Their GONOSUMDB is rightly configured.
As the Athens company maintainer, you can run Athens with the following configuration:
Athens allows the operator running the server to specify a list of patterns to not lookup via the upstream sum provider:
`NoSumPatterns = ["github.com/mycompany/*] # or comma separted env var: ATHENS_GONOSUM_PATTERNS`
```toml
NoSumPatterns = ["github.com/mycompany/*", "github.com/secret/*"]
```
This will ensure that when Go sends a request to `<athens-url/sumdb/sum.golang.org/github.com/mycompany/secret-repo@v1.0.0>`, Athens will return a 403 and failing the build ensuring that the client knows something is not configured correctly and also never leaking those import paths
Or you can do it with an environment variable:
```console
$ export ATHENS_GONOSUM_PATTERNS="github.com/mycompany/*,github.com/secret/*"
```
>In both of the above configuration examples, there are two patterns specified, and they are separated by a comma (`,`) in both cases. When you are using the environment variable (`export ATHENS_GONOSUM_PATTERNS`), make sure you don't use brackes (`[` and `]`).
Either way, this configuration will ensure that when Go sends a request to `<athens-url>/sumdb/sum.golang.org/github.com/mycompany/secret-repo@v1.0.0`, Athens will return a 403 and failing the build ensuring that the client knows something is not configured correctly and also never leaking those import paths.