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 // Keep-web does not support TLS natively. Typically, it is installed
  53 // behind a proxy like nginx.
  54 //
  55 // Here is an example nginx configuration.
  56 //
  57 //      http {
  58 //        upstream keep-web {
  59 //          server localhost:1234;
  60 //        }
  61 //        server {
  62 //          listen *:443 ssl;
  63 //          server_name collections.example.com *.collections.example.com ~.*--collections.example.com;
  64 //          ssl_certificate /root/wildcard.example.com.crt;
  65 //          ssl_certificate_key /root/wildcard.example.com.key;
  66 //          location  / {
  67 //            proxy_pass http://keep-web;
  68 //            proxy_set_header Host $host;
  69 //            proxy_set_header X-Forwarded-For $remote_addr;
  70 //          }
  71 //        }
  72 //      }
  73 //
  74 // It is not necessary to run keep-web on the same host as the nginx
  75 // proxy. However, TLS is not used between nginx and keep-web, so
  76 // intervening networks must be secured by other means.
  77 //
  78 // Anonymous downloads
  79 //
  80 // The "Users.AnonymousUserToken" configuration entry used when
  81 // when processing anonymous requests, i.e., whenever a web client
  82 // does not supply its own Arvados API token via path, query string,
  83 // cookie, or request header.
  84 //
  85 //   Clusters:
  86 //     zzzzz:
  87 //       Users:
  88 //         AnonymousUserToken: "xxxxxxxxxxxxxxxxxxxxxxx"
  89 //
  90 // See http://doc.arvados.org/install/install-keep-web.html for examples.
  91 //
  92 // Download URLs
  93 //
  94 // See http://doc.arvados.org/api/keep-web-urls.html
  95 //
  96 // Attachment-Only host
  97 //
  98 // It is possible to serve untrusted content and accept user
  99 // credentials at the same origin as long as the content is only
 100 // downloaded, never executed by browsers. A single origin (hostname
 101 // and port) can be designated as an "attachment-only" origin: cookies
 102 // will be accepted and all responses will have a
 103 // "Content-Disposition: attachment" header. This behavior is invoked
 104 // only when the designated origin matches exactly the Host header
 105 // provided by the client or downstream proxy.
 106 //
 107 //   Clusters:
 108 //     zzzzz:
 109 //       Services:
 110 //         WebDAVDownload:
 111 //           ExternalURL: "https://domain.example:9999"
 112 //
 113 // Trust All Content mode
 114 //
 115 // In TrustAllContent mode, Keep-web will accept credentials (API
 116 // tokens) and serve any collection X at
 117 // "https://collections.example.com/c=X/path/file.ext".  This is
 118 // UNSAFE except in the special case where everyone who is able write
 119 // ANY data to Keep, and every JavaScript and HTML file written to
 120 // Keep, is also trusted to read ALL of the data in Keep.
 121 //
 122 // In such cases you can enable trust-all-content mode.
 123 //
 124 //   Clusters:
 125 //     zzzzz:
 126 //       Collections:
 127 //         TrustAllContent: true
 128 //
 129 // When TrustAllContent is enabled, the only effect of the
 130 // Attachment-Only host setting is to add a "Content-Disposition:
 131 // attachment" header.
 132 //
 133 //   Clusters:
 134 //     zzzzz:
 135 //       Services:
 136 //         WebDAVDownload:
 137 //           ExternalURL: "https://domain.example:9999"
 138 //       Collections:
 139 //         TrustAllContent: true
 140 //
 141 // Depending on your site configuration, you might also want to enable
 142 // the "trust all content" setting in Workbench. Normally, Workbench
 143 // avoids redirecting requests to keep-web if they depend on
 144 // TrustAllContent being enabled.
 145 //
 146 // Metrics
 147 //
 148 // Keep-web exposes request metrics in Prometheus text-based format at
 149 // /metrics. The same information is also available as JSON at
 150 // /metrics.json.
 151 //
 152 package main