docs/configuration.txt

   1
   2 = Configuring a Tahoe node =
   3
   4 A Tahoe node is configured by writing files to its base directory. These
   5 files are read by the node when it starts, so each time you change them, you
   6 need to restart the node.
   7
   8 The node also writes state to its base directory, so it will create files on
   9 its own.
  10
  11 This document contains a complete list of the config files that are examined
  12 by the client node, as well as the state files that you'll observe in its
  13 base directory.
  14
  15 == Client Configuration ==
  16
  17 introducer.furl and vdrive.furl (mandatory): These FURLs tell the client how
  18 to connect to the introducer/vdrive server. Each Tahoe grid is defined by
  19 this pair. They are created by the introducer/vdrive-server node and written
  20 into its base directory when it starts, whereupon they should be published to
  21 everyone who wishes to attach a client to that grid
  22
  23 webport (optional): This controls where the client's webserver should listen,
  24 providing vdrive access as defined in webapi.txt . This file should contain a
  25 Twisted "strports" specification, such as "8080" or
  26 "tcp:8080:interface=127.0.0.1".
  27
  28 client.port (optional): This controls which port the node listens on. If not
  29 provided, the node will ask the kernel for any available port, and write it
  30 to this file so that subsequent runs will re-use the same port.
  31
  32 advertised_ip_addresses (optional): The node normally uses tools like
  33 'ifconfig' to determine the set of IP addresses on which it can be reached
  34 from nodes both near and far. The node introduces itself to the rest of the
  35 grid with a FURL that contains a series of (ipaddr, port) pairs which other
  36 nodes will use to contact this one. By providing this file, you can add to
  37 this list. This can be useful if your node is running behind a firewall, but
  38 you have created a port-forwarding to allow the outside world to access it.
  39 Each line must have a dotted-quad IP address and an optional :portnum
  40 specification:
  41
  42  123.45.67.89
  43  44.55.66.77:8098
  44
  45 Lines that do not provide a port number will use the same client.port as the
  46 automatically-discovered addresses.
  47
  48 authorized_keys.SSHPORT: This enables an SSH-based interactive Python shell,
  49 which can be used to inspect the internal state of the node, for debugging.
  50 To cause the node to accept SSH connections on port 8022, symlink
  51 "authorized_keys.8022" to your ~/.ssh/authorized_keys file, and it will
  52 accept the same keys as the rest of your account.
  53
  54
  55 == Node State ==
  56
  57 node.pem : This contains an SSL private-key certificate. The node generates
  58 this the first time it is started, and re-uses it on subsequent runs. This
  59 certificate allows the node to have a cryptographically-strong identifier
  60 (the Foolscap "TubID"), and to establish secure connections to other nodes.
  61
  62 global_root.uri: The first time the client contacts the vdrive-server, it
  63 retrieves the dirnode URI of the global root directory, and writes it into
  64 this file. On subsequent runs, this URI is used each time the user accesses
  65 the global vdrive.
  66
  67 my_vdrive.uri: The first time the client contacts the vdrive-server, it will
  68 create a brand new directory to use as the non-shared private vdrive root,
  69 and it stores the dirnode URI of this directory in this file. On subsequent
  70 runs, it will read the URI from this file to provide access to the private
  71 vdrive.
  72
  73 storage/ : Nodes which host StorageServers will create this directory to hold
  74 shares of files on behalf of other clients. There will be a directory
  75 underneath it for each StorageIndex for which this node is holding shares.
  76 There is also an "incoming" directory where partially-completed shares are
  77 held while they are being received.
  78
  79 client.tac : this file defines the client, by constructing the actual Client
  80 instance each time the node is started. It is used by the 'twistd'
  81 daemonization program (in the "-y" mode), which is run internally by the
  82 "tahoe start" command. This file is created by the "tahoe create-client"
  83 command.
  84
  85 control.furl : this file contains a FURL that provides access to a control
  86 port on the client node, from which files can be uploaded and downloaded.
  87 This file is created with permissions that prevent anyone else from reading
  88 it, to insure that only the owner of the client node can use this feature.
  89 This port is intended for debugging and testing use.
  90
  91 == Introducer/vdrive-server configuration ==
  92
  93 Introducer/vdrive-server nodes use the same 'advertised_ip_addresses' file
  94 as client nodes. They also use 'authorized_keys.SSHPORT'.
  95
  96 encoding_parameters (optional): This file sets the encoding parameters that
  97 will be distributed to all client nodes and used when they encode files
  98 (unless locally overridden). It should contain three numbers, separated by
  99 whitespace, called "needed", "desired", and "total".
 100
 101  "needed": this is the number of shares that will be needed to reconstruct
 102            the file. Each share that is pushed to a StorageServer will be
 103            the size of the original file divided by this number.
 104  "desired": the encoding/upload process will be happy if it can push
 105             this many shares to StorageServers. If it cannot, it will
 106             report failure.
 107  "total": this is the total number of shares that will be produced. The
 108           expansion factor (i.e. the amount of space consumed on the whole
 109           grid divided by the size of the file) will be total/needed. It does
 110           not make a lot of sense to have "total" be much larger than the
 111           maximum number of storage nodes you expect to ever have.
 112
 113 The default value of encoding_parameters is "3 7 10".
 114
 115
 116 == Introducer/vdrive-server state ==
 117
 118 The Introducer / Virtual-Drive Server node maintains some different state
 119 than regular client nodes. Both of these services are currently hosted inside
 120 the same node, although keeping the FURLs in separate files will make it
 121 easier to split these services in the future.
 122
 123 introducer.furl : This is generated the first time the introducer node is
 124 started, and used again on subsequent runs, to give the introduction service
 125 a persistent long-term identity. This file should be published and copied
 126 into new client nodes before they are started for the first time.
 127
 128 vdrive.furl : This is also generated the first time the node is started, and
 129 re-used on later runs. This FURL provides access to the vdrive service, used
 130 both to create+access all dirnodes and to learn about the global shared root
 131 vdrive.
 132
 133 introducer.port : this serves exactly the same purpose as 'client.port', but
 134 has a different name to make it clear what kind of node is being run.
 135
 136 vdrive/ : this directory is created by the vdrive service to hold the
 137 encrypted contents of dirnodes on behalf of all clients. It contains one file
 138 per dirnode, plus a file named 'root' which contains the binary storage index
 139 of the global shared root vdrive.
 140
 141 introducer.tac : this file is like client.tac but defines an
 142 introducer/vdrive-server node instead of a client node.
 143
 144 == Other files ==
 145
 146 logs/ : Each Tahoe node creates a directory to hold the log messages produced
 147 as the node runs. These logfiles are created and rotated by the "twistd"
 148 daemonization program, so logs/twistd.log will contain the most recent
 149 messages, logs/twistd.log.1 will contain the previous ones, logs/twistd.log.2
 150 will be older still, and so on. twistd rotates logfiles after they grow
 151 beyond 1MB in size. If the space consumed by logfiles becomes troublesome,
 152 they should be pruned: a cron job to delete all files that were created more
 153 than a month ago in this logs/ directory should be sufficient.
 154
 155 my_nodeid : this is written by all nodes after startup, and contains a
 156 base32-encoded (i.e. human-readable) NodeID that identifies this specific
 157 node. This NodeID is the same string that gets displayed on the web page (in
 158 the "which peers am I connected to" list), and the shortened form (the first
 159 characters) is recorded in various log messages.
 160