X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/df9cb8ad02aaee8045cb31e207fd9c6a13c01684..086fdccf436bb68d38f482c4e1418c1290ed7c0c:/services/keep-web/doc.go diff --git a/services/keep-web/doc.go b/services/keep-web/doc.go index dbf4f5b825..4f7d2ca968 100644 --- a/services/keep-web/doc.go +++ b/services/keep-web/doc.go @@ -1,57 +1,150 @@ -// Keep-web provides read-only HTTP access to files stored in Keep. It -// serves public data to anonymous and unauthenticated clients, and -// accepts authentication via Arvados tokens. It can be installed -// anywhere with access to Keep services, typically behind a web proxy -// that provides SSL support. +// Copyright (C) The Arvados Authors. All rights reserved. // -// Given that this amounts to a web hosting service for arbitrary -// content, it is vital to ensure that at least one of the following is -// true: -// -// Usage -// -// Listening: -// -// keep-web -address=:1234 -// -// Start an HTTP server on port 1234. -// -// keep-web -address=1.2.3.4:1234 -// -// Start an HTTP server on port 1234, on the interface with IP address 1.2.3.4. -// -// Keep-web does not support SSL natively. Typically, it is installed -// behind a proxy like nginx. -// -package main +// SPDX-License-Identifier: AGPL-3.0 -// TODO(TC): Implement -// -// Trusted content -// -// Normally, Keep-web is installed using a wildcard DNS entry and a -// wildcard HTTPS certificate, serving data from collection X at -// ``https://X.dl.example.com/path/file.ext''. -// -// It will also serve publicly accessible data at -// ``https://dl.example.com/collections/X/path/file.txt'', but it does not -// accept any kind of credentials at paths like these. -// -// In "trust all content" mode, Keep-web will accept credentials (API +// Keep-web provides read/write HTTP (WebDAV) access to files stored +// in Keep. It serves public data to anonymous and unauthenticated +// clients, and serves private data to clients that supply Arvados API +// tokens. It can be installed anywhere with access to Keep services, +// typically behind a web proxy that supports TLS. +// +// See http://doc.arvados.org/install/install-keep-web.html. +// +// # Configuration +// +// The default cluster configuration file location is +// /etc/arvados/config.yml. +// +// Example configuration file +// +// Clusters: +// zzzzz: +// SystemRootToken: "" +// Services: +// Controller: +// ExternalURL: "https://example.com" +// Insecure: false +// WebDAV: +// InternalURLs: +// "http://:1234/": {} +// WebDAVDownload: +// InternalURLs: +// "http://:1234/": {} +// ExternalURL: "https://download.example.com/" +// Users: +// AnonymousUserToken: "xxxxxxxxxxxxxxxxxxxx" +// Collections: +// TrustAllContent: false +// +// # Starting the server +// +// Start a server using the default config file +// /etc/arvados/config.yml: +// +// keep-web +// +// Start a server using the config file /path/to/config.yml: +// +// keep-web -config /path/to/config.yml +// +// # Proxy configuration +// +// Typically, keep-web is installed behind a proxy like nginx. +// +// Here is an example nginx configuration. +// +// http { +// upstream keep-web { +// server localhost:1234; +// } +// server { +// listen *:443 ssl; +// server_name collections.example.com *.collections.example.com ~.*--collections.example.com; +// ssl_certificate /root/wildcard.example.com.crt; +// ssl_certificate_key /root/wildcard.example.com.key; +// location / { +// proxy_pass http://keep-web; +// proxy_set_header Host $host; +// proxy_set_header X-Forwarded-For $remote_addr; +// } +// } +// } +// +// It is not necessary to run keep-web on the same host as the nginx +// proxy. However, if TLS is not used between nginx and keep-web, the +// intervening networks must be secured by other means. +// +// # Anonymous downloads +// +// The "Users.AnonymousUserToken" configuration entry used when +// when processing anonymous requests, i.e., whenever a web client +// does not supply its own Arvados API token via path, query string, +// cookie, or request header. +// +// Clusters: +// zzzzz: +// Users: +// AnonymousUserToken: "xxxxxxxxxxxxxxxxxxxxxxx" +// +// See http://doc.arvados.org/install/install-keep-web.html for examples. +// +// # Download URLs +// +// See http://doc.arvados.org/api/keep-web-urls.html +// +// # Attachment-Only host +// +// It is possible to serve untrusted content and accept user +// credentials at the same origin as long as the content is only +// downloaded, never executed by browsers. A single origin (hostname +// and port) can be designated as an "attachment-only" origin: cookies +// will be accepted and all responses will have a +// "Content-Disposition: attachment" header. This behavior is invoked +// only when the designated origin matches exactly the Host header +// provided by the client or downstream proxy. +// +// Clusters: +// zzzzz: +// Services: +// WebDAVDownload: +// ExternalURL: "https://domain.example:9999" +// +// # Trust All Content mode +// +// In TrustAllContent mode, Keep-web will accept credentials (API // tokens) and serve any collection X at -// "https://dl.example.com/collections/X/path/file.ext". This is +// "https://collections.example.com/c=X/path/file.ext". This is // UNSAFE except in the special case where everyone who is able write // ANY data to Keep, and every JavaScript and HTML file written to // Keep, is also trusted to read ALL of the data in Keep. // // In such cases you can enable trust-all-content mode. // -// keep-web -trust-all-content [...] -// -// In the general case, this should not be enabled: A web page stored -// in collection X can execute JavaScript code that uses the current -// viewer's credentials to download additional data -- data which is -// accessible to the current viewer, but not to the author of -// collection X -- from the same origin (``https://dl.example.com/'') -// and upload it to some other site chosen by the author of collection -// X. +// Clusters: +// zzzzz: +// Collections: +// TrustAllContent: true +// +// When TrustAllContent is enabled, the only effect of the +// Attachment-Only host setting is to add a "Content-Disposition: +// attachment" header. +// +// Clusters: +// zzzzz: +// Services: +// WebDAVDownload: +// ExternalURL: "https://domain.example:9999" +// Collections: +// TrustAllContent: true +// +// Depending on your site configuration, you might also want to enable +// the "trust all content" setting in Workbench. Normally, Workbench +// avoids redirecting requests to keep-web if they depend on +// TrustAllContent being enabled. +// +// # Metrics +// +// Keep-web exposes request metrics in Prometheus text-based format at +// /metrics. The same information is also available as JSON at +// /metrics.json. +package keepweb