services/keep-web/doc.go

   1 // Copyright (C) The Arvados Authors. All rights reserved.
   2 //
   3 // SPDX-License-Identifier: AGPL-3.0
   4
   5 // Keep-web provides read/write HTTP (WebDAV) access to files stored
   6 // in Keep. It serves public data to anonymous and unauthenticated
   7 // clients, and serves private data to clients that supply Arvados API
   8 // tokens. It can be installed anywhere with access to Keep services,
   9 // typically behind a web proxy that supports TLS.
  10 //
  11 // See http://doc.arvados.org/install/install-keep-web.html.
  12 //
  13 // # Configuration
  14 //
  15 // The default cluster configuration file location is
  16 // /etc/arvados/config.yml.
  17 //
  18 // Example configuration file
  19 //
  20 //      Clusters:
  21 //        zzzzz:
  22 //          SystemRootToken: ""
  23 //          Services:
  24 //            Controller:
  25 //              ExternalURL: "https://example.com"
  26 //              Insecure: false
  27 //            WebDAV:
  28 //              InternalURLs:
  29 //                "http://:1234/": {}
  30 //            WebDAVDownload:
  31 //              InternalURLs:
  32 //                "http://:1234/": {}
  33 //              ExternalURL: "https://download.example.com/"
  34 //          Users:
  35 //            AnonymousUserToken: "xxxxxxxxxxxxxxxxxxxx"
  36 //          Collections:
  37 //            TrustAllContent: false
  38 //
  39 // # Starting the server
  40 //
  41 // Start a server using the default config file
  42 // /etc/arvados/config.yml:
  43 //
  44 //      keep-web
  45 //
  46 // Start a server using the config file /path/to/config.yml:
  47 //
  48 //      keep-web -config /path/to/config.yml
  49 //
  50 // # Proxy configuration
  51 //
  52 // Typically, keep-web is installed behind a proxy like nginx.
  53 //
  54 // Here is an example nginx configuration.
  55 //
  56 //      http {
  57 //        upstream keep-web {
  58 //          server localhost:1234;
  59 //        }
  60 //        server {
  61 //          listen *:443 ssl;
  62 //          server_name collections.example.com *.collections.example.com ~.*--collections.example.com;
  63 //          ssl_certificate /root/wildcard.example.com.crt;
  64 //          ssl_certificate_key /root/wildcard.example.com.key;
  65 //          location  / {
  66 //            proxy_pass http://keep-web;
  67 //            proxy_set_header Host $host;
  68 //            proxy_set_header X-Forwarded-For $remote_addr;
  69 //          }
  70 //        }
  71 //      }
  72 //
  73 // It is not necessary to run keep-web on the same host as the nginx
  74 // proxy. However, if TLS is not used between nginx and keep-web, the
  75 // intervening networks must be secured by other means.
  76 //
  77 // # Anonymous downloads
  78 //
  79 // The "Users.AnonymousUserToken" configuration entry used when
  80 // when processing anonymous requests, i.e., whenever a web client
  81 // does not supply its own Arvados API token via path, query string,
  82 // cookie, or request header.
  83 //
  84 //      Clusters:
  85 //        zzzzz:
  86 //          Users:
  87 //            AnonymousUserToken: "xxxxxxxxxxxxxxxxxxxxxxx"
  88 //
  89 // See http://doc.arvados.org/install/install-keep-web.html for examples.
  90 //
  91 // # Download URLs
  92 //
  93 // See http://doc.arvados.org/api/keep-web-urls.html
  94 //
  95 // # Attachment-Only host
  96 //
  97 // It is possible to serve untrusted content and accept user
  98 // credentials at the same origin as long as the content is only
  99 // downloaded, never executed by browsers. A single origin (hostname
 100 // and port) can be designated as an "attachment-only" origin: cookies
 101 // will be accepted and all responses will have a
 102 // "Content-Disposition: attachment" header. This behavior is invoked
 103 // only when the designated origin matches exactly the Host header
 104 // provided by the client or downstream proxy.
 105 //
 106 //      Clusters:
 107 //        zzzzz:
 108 //          Services:
 109 //            WebDAVDownload:
 110 //              ExternalURL: "https://domain.example:9999"
 111 //
 112 // # Trust All Content mode
 113 //
 114 // In TrustAllContent mode, Keep-web will accept credentials (API
 115 // tokens) and serve any collection X at
 116 // "https://collections.example.com/c=X/path/file.ext".  This is
 117 // UNSAFE except in the special case where everyone who is able write
 118 // ANY data to Keep, and every JavaScript and HTML file written to
 119 // Keep, is also trusted to read ALL of the data in Keep.
 120 //
 121 // In such cases you can enable trust-all-content mode.
 122 //
 123 //      Clusters:
 124 //        zzzzz:
 125 //          Collections:
 126 //            TrustAllContent: true
 127 //
 128 // When TrustAllContent is enabled, the only effect of the
 129 // Attachment-Only host setting is to add a "Content-Disposition:
 130 // attachment" header.
 131 //
 132 //      Clusters:
 133 //        zzzzz:
 134 //          Services:
 135 //            WebDAVDownload:
 136 //              ExternalURL: "https://domain.example:9999"
 137 //          Collections:
 138 //            TrustAllContent: true
 139 //
 140 // Depending on your site configuration, you might also want to enable
 141 // the "trust all content" setting in Workbench. Normally, Workbench
 142 // avoids redirecting requests to keep-web if they depend on
 143 // TrustAllContent being enabled.
 144 //
 145 // # Metrics
 146 //
 147 // Keep-web exposes request metrics in Prometheus text-based format at
 148 // /metrics. The same information is also available as JSON at
 149 // /metrics.json.
 150 package keepweb