diff --git a/docs/configuration.rst b/docs/configuration.rst index 3d7d68ef3..1f5a862b0 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -958,6 +958,9 @@ If you omit the introducer definitions from both ``tahoe.cfg`` and "introducerless" clients must be configured with static servers (described below), or they will not be able to upload and download files. + +.. _server_list: + Static Server Definitions ========================= diff --git a/docs/proposed/grid-manager/managed-grid.rst b/docs/proposed/grid-manager/managed-grid.rst new file mode 100644 index 000000000..05844d9be --- /dev/null +++ b/docs/proposed/grid-manager/managed-grid.rst @@ -0,0 +1,247 @@ +(This document is "in-progress", with feedback and input from two +devchats with Brain Warner and exarkun as well as other input, +discussion and edits from exarkun. It is NOT done). Search for +"DECIDE" for open questions. + + +Managed Grid +============ + +In a grid using an Introducer, a client will use any storage-server +the Introducer announces. This means that anyone with the Introducer +fURL can connect storage to the grid. + +Sometimes, this is just what you want! + +For some use-cases, though, you want to have clients only use certain +servers. One case might be a "managed" grid, where some entity runs +the grid; clients of this grid don't want their uploads to go to +"unmanaged" storage if some other client decides to provide storage. + +One way to limit which storage servers a client connects to is via the +"server list" (:ref:`server_list`) (aka "Introducer-less" +mode). Clients are given static lists of storage-servers, and connect +only to those. This means manually updating these lists if the storage +servers change, however. + +Another method is for clients to use `[client] peers.preferred=` +configuration option (XXX link? appears undocumented), which suffers +from a similar disadvantage. + + +Grid Manager +------------ + +A "grid-manager" consists of some data defining a keypair along with +some other details and Tahoe sub-commands to manipulate the data and +produce certificates to give to storage-servers. Certificates assert +the statement: "Grid Manager X suggests you use storage-server Y to +upload shares to" (X and Y are public-keys). Such a certificate +consists of: + + - a version (currently 1) + - the public-key of a storage-server + - an expiry timestamp + - a signature of the above + +A client will always use any storage-server for downloads (expired +certificate, or no certificate) because we check the ciphertext and +re-assembled plaintext agains the keys in the capability; +"grid-manager" certificates only control uploads. + + +Grid Manager Data Storage +------------------------- + +The data defining the grid-manager is stored in an arbitrary +directory, which you indicate with the ``--config`` option (in the +future, we may add the ability to store the data directly in a grid, +at which time you may be able to pass a directory-capability to this +option). + +If you don't want to store the configuration on disk at all, you may +use ``--config -`` (that's a dash) and write a valid JSON (YAML? I'm +guessing JSON is easier to deal with here, more-interoperable?) +configuration to stdin. + +All commands take the ``--config`` option, and they all behave +similarly for "data from stdin" versus "data from disk". + +DECIDE: + - config is YAML or JSON? + + +tahoe grid-manager create +````````````````````````` + +Create a new grid-manager. + +If you specify ``--config -`` then a new grid-manager configuration is +written to stdout. Otherwise, a new grid-manager is created in the +directory specified by the ``--config`` option. It is an error if the +directory already exists. + + +tahoe grid-manager show-identity +```````````````````````````````` + +Print out a grid-manager's public key. This key is derived from the +private-key of the grid-manager, so a valid grid-manager config must +be given via ``--config`` + +This public key is what is put in clients' configuration to actually +validate and use grid-manager certificates. + + +tahoe grid-manager add +`````````````````````` + +Takes two args: ``name pubkey``. The ``name`` is an arbitrary local +identifier and the pubkey is the encoded key from a ``node.pubkey`` +file in the storage-server's node directory (with no whitespace). + +This adds a new storage-server to a Grid Manager's +configuration. (Since it mutates the configuration, if you used +``--config -`` the new configuration will be printed to stdout). + + +tahoe grid-manager sign +``````````````````````` + +Takes one arg: ``name``, the petname used previous in a ``tahoe +grid-manager add`` command. + +Note that this mutates the state of the grid-manager if it is on disk, +by adding this certificate to our collection of issued +certificates. If you used ``--config -``, the certificate isn't +persisted anywhere except to stdout (so if you wish to keep it +somewhere, that is up to you). + +This command creates a new "version 1" certificate for a +storage-server (identified by its public key). The new certificate is +printed to stdout. If you stored the config on disk, the new +certificate will (also) be in a file named like +``pub-v0-kioayfth3g7zaitcskln64ddx7tkd6xoe7dbr62uogmlwxtxudpq.cert``. + + +Enrolling a Storage Server +-------------------------- + +tahoe admin add-grid-manager-cert +````````````````````````````````` + +- `--filename`: the file to read the cert from (default: stdin) +- `--name`: the name of this certificate (default: "default") + +Import a "version 1" storage-certificate produced by a grid-manager +(probably: a storage server may have zero or more such certificates +installed; for now just one is sufficient). You will have to re-start +your node after this. Subsequent announcements to the Introducer will +include this certificate. + + +Enrolling a Client +------------------ + +tahoe add-grid-manager +`````````````````````` + +- ``--name``: a petname to call this Grid Manager (default: "default") + +For clients to start using a Grid Manager, they must add a +public-key. A client may have any number of grid-managers, so each one +has a name. If you don't supply ``--name`` then ``"default"`` is used. + +This command takes a single argument, which is the hex-encoded public +key of the Grid Manager. The client will have to be re-started once +this change is made. + + +Example Setup of a New Managed Grid +----------------------------------- + +We'll store our Grid Manager configuration on disk, in +``~/grid-manager``. To initialize this directory:: + + tahoe grid-manager create --config ~/grid-manager + +This example creates an actual grid, but it's all just on one machine +with different "node directories". Usually of course each one would be +on a separate computer. + +(If you already have a grid, you can :ref:`skip ahead `.) + +First of all, create an Introducer. Note that we actually have to run +it briefly before it creates the "Introducer fURL" we want for the +next steps. + + tahoe create-introducer --listen=tcp --port=5555 --location=tcp:localhost:5555 ./introducer + tahoe -d introducer run + (Ctrl-C to stop it after a bit) + +Next, we attach a couple of storage nodes:: + + tahoe create-node --introducer $(cat introducer/private/introducer.furl) --nickname storage0 --webport 6001 --webport 6002 --location tcp:localhost:6003 --port 6003 ./storage0 + tahoe create-node --introducer $(cat introducer/private/introducer.furl) --nickname storage1 --webport 6101 --webport 6102 --location tcp:localhost:6103 --port 6103 ./storage1 + daemonize tahoe -d storage0 run + daemonize tahoe -d storage1 run + +.. _skip_ahead: + +We can now ask the Grid Manager to create certificates for our new +storage servers:: + + tahoe grid-manager --config ~/grid-manager add-storage --pubkey $(cat storage0/node.pubkey) > storage0.cert + tahoe grid-manager --config ~/grid-manager add-storage --pubkey $(cat storage1/node.pubkey) > storage1.cert + + # enroll server0 (using file) + kill $(cat storage0/twistd.pid) + tahoe -d storage0 admin add-grid-manager-cert --filename storage0.cert + daemonize tahoe -d storage0 run + + # enroll server1 (using stdin) + kill $(cat storage1/twistd.pid) + cat storage1.cert | tahoe -d storage1 admin add-grid-manager-cert + daemonize tahoe -d storage1 run + +Now try adding a new storage server ``storage2``. This client can join +the grid just fine, and announce itself to the Introducer as providing +storage:: + + tahoe create-node --introducer $(cat introducer/private/introducer.furl) --nickname storage2 --webport 6301 --webport 6302 --location tcp:localhost:6303 --port 6303 ./storage2 + daemonize tahoe -d storage2 run + +At this point any client will upload to any of these three +storage-servers. Make a client "alice" and try! + +:: + + tahoe create-client --introducer $(cat introducer/private/introducer.furl) --nickname alice --webport 6301 --shares-total=3 --shares-needed=2 --shares-happy=3 ./alice + daemonize tahoe -d alice run + tahoe -d alice mkdir # prints out a dir-cap + find storage2/storage/shares # confirm storage2 has a share + +Now we want to make Alice only upload to the storage servers that the +grid-manager has given certificates to (``storage0`` and +``storage1``). We need the grid-manager's public key to put in Alice's +configuration:: + + kill $(cat alice/twistd.pid) + tahoe -d alice add-grid-manager --name work-grid $(tahoe grid-manager --config ~/grid-manager show-identity) + daemonize tahoe -d alice start + +DECIDE: + - should the grid-manager be identified by a certificate? exarkun + points out: --name seems like the hint of the beginning of a + use-case for certificates rather than bare public keys?). + +Since we made Alice's parameters require 3 storage servers to be +reachable (`--happy=3`), all their uploads should now fail (so `tahoe +mkdir` will fail) because they won't use storage2 and can't "achieve +happiness". + +You can check Alice's "Welcome" page (where the list of connected servers +is) at http://localhost:6301/ and should be able to see details about +the "work-grid" Grid Manager that you added. When any Grid Managers +are enabled, each storage-server line will show whether it has a valid +cerifiticate or not (and how much longer it's valid until).