Tahoe-LAFS Documentation Release 1.x The Tahoe-LAFS Developers January 19, 2017 Contents 1 Welcome to Tahoe-LAFS! 3 1.1 What is Tahoe-LAFS?..........................................3 1.2 What is “provider-independent security”?................................3 1.3 Access Control..............................................4 1.4 Get Started................................................4 1.5 License..................................................4 2 Installing Tahoe-LAFS 5 2.1 First: In Case Of Trouble.........................................5 2.2 Pre-Packaged Versions..........................................5 2.3 Preliminaries...............................................5 2.4 Install the Latest Tahoe-LAFS Release.................................6 2.5 Running the tahoe executable.....................................8 2.6 Running the Self-Tests..........................................8 2.7 Common Problems............................................9 2.8 Using Tahoe-LAFS............................................9 3 How To Run Tahoe-LAFS 11 3.1 Introduction............................................... 11 3.2 Do Stuff With It............................................. 12 3.3 Socialize................................................. 13 3.4 Complain................................................. 13 4 Configuring a Tahoe-LAFS node 15 4.1 Node Types................................................ 16 4.2 Overall Node Configuration....................................... 16 4.3 Connection Management......................................... 20 4.4 Client Configuration........................................... 23 4.5 Frontend Configuration......................................... 24 4.6 Storage Server Configuration...................................... 25 4.7 Running A Helper............................................ 25 4.8 Running An Introducer.......................................... 26 4.9 Other Files in BASEDIR......................................... 26 4.10 Additional Introducer Definitions.................................... 27 4.11 Static Server Definitions......................................... 28 4.12 Other files................................................ 29 4.13 Example................................................. 30 4.14 Old Configuration Files......................................... 30 i 5 Tahoe-LAFS Architecture 31 5.1 Overview................................................. 31 5.2 The Key-Value Store........................................... 32 5.3 File Encoding............................................... 32 5.4 Capabilities................................................ 33 5.5 Server Selection............................................. 33 5.6 Swarming Download, Trickling Upload................................. 35 5.7 The Filesystem Layer.......................................... 35 5.8 Leases, Refreshing, Garbage Collection................................. 35 5.9 File Repairer............................................... 36 5.10 Security.................................................. 36 5.11 Reliability................................................ 37 6 The Tahoe-LAFS CLI commands 39 6.1 Overview................................................. 39 6.2 CLI Command Overview........................................ 39 6.3 Node Management............................................ 40 6.4 Filesystem Manipulation......................................... 41 6.5 Storage Grid Maintenance........................................ 47 6.6 Debugging................................................ 47 7 The Tahoe REST-ful Web API 49 7.1 Enabling the web-API port........................................ 50 7.2 Basic Concepts: GET, PUT, DELETE, POST.............................. 50 7.3 URLs................................................... 51 7.4 Slow Operations, Progress, and Cancelling............................... 52 7.5 Programmatic Operations........................................ 53 7.6 Browser Operations: Human-oriented interfaces............................ 63 7.7 Other Useful Pages............................................ 75 7.8 Static Files in /public_html........................................ 77 7.9 Safety and Security Issues – Names vs. URIs.............................. 77 7.10 Concurrency Issues............................................ 78 7.11 Access Blacklist............................................. 78 7.12 URLs and HTTP and UTF-8....................................... 79 8 Tahoe-LAFS SFTP and FTP Frontends 81 8.1 SFTP/FTP Background......................................... 81 8.2 Tahoe-LAFS Support........................................... 81 8.3 Creating an Account File......................................... 82 8.4 Running An Account Server (accounts.url)............................... 82 8.5 Configuring SFTP Access........................................ 83 8.6 Configuring FTP Access......................................... 83 8.7 Dependencies............................................... 84 8.8 Immutable and Mutable Files...................................... 84 8.9 Known Issues............................................... 85 9 Tahoe-LAFS Magic Folder Frontend 87 9.1 Introduction............................................... 87 9.2 Configuration............................................... 87 9.3 Known Issues and Limitations With Magic-Folder........................... 88 10 Download status 89 10.1 Introduction............................................... 89 10.2 What’s involved in a download?..................................... 89 10.3 Data on the download-status page.................................... 90 ii 11 Known Issues 93 11.1 Known Issues in Tahoe-LAFS v1.10.3, released 30-Mar-2016..................... 93 11.2 Known Issues in Tahoe-LAFS v1.9.0, released 31-Oct-2011...................... 97 11.3 Known Issues in Tahoe-LAFS v1.8.2, released 30-Jan-2011...................... 97 12 How To Configure A Server 99 12.1 Manual Configuration.......................................... 99 12.2 Automatic Configuration......................................... 99 12.3 Deployment Scenarios.......................................... 100 13 The Tahoe Upload Helper 103 13.1 Overview................................................. 103 13.2 Setting Up A Helper........................................... 104 13.3 Using a Helper.............................................. 104 13.4 Other Helper Modes........................................... 105 14 The Convergence Secret 107 14.1 What Is It?................................................ 107 14.2 What If I Change My Convergence Secret?............................... 107 14.3 How To Use It.............................................. 108 15 Garbage Collection in Tahoe 109 15.1 Overview................................................. 109 15.2 Client-side Renewal........................................... 109 15.3 Server Side Expiration.......................................... 110 15.4 Expiration Progress........................................... 112 15.5 Future Directions............................................. 112 16 Statement on Backdoors 115 17 Donations 117 17.1 Governance................................................ 117 17.2 Transparent Accounting......................................... 117 17.3 Expenditure Addresses.......................................... 117 17.4 Historical Donation Addresses...................................... 118 17.5 Validation................................................. 118 18 Expenses paid by donated BTC 119 18.1 Budget Items............................................... 119 19 Things To Be Careful About As We Venture Boldly Forth 123 19.1 Timing Attacks.............................................. 123 20 Avoiding Write Collisions in Tahoe 125 21 Magic Folder Set-up Howto 127 21.1 This document.............................................. 127 21.2 Setting up a local test grid........................................ 127 21.3 Setting up Magic Folder......................................... 128 21.4 Testing.................................................. 129 21.5 Configuration............................................... 129 22 The Tahoe BackupDB 131 22.1 Overview................................................. 131 22.2 Schema.................................................. 131 22.3 Upload Operation............................................ 132 iii 22.4 Directory Operations........................................... 133 23 Using Tahoe-LAFS with an anonymizing network: Tor, I2P 135 23.1 Overview................................................. 135 23.2 Use cases................................................. 135 23.3 Software Dependencies......................................... 136 23.4 Connection configuration........................................ 137 23.5 Anonymity configuration......................................... 137 23.6 Performance and security issues..................................... 139 24 Node Keys in Tahoe-LAFS 143 24.1 Why Announcements Are Signed.................................... 143 24.2 How The Node ID Is Computed..................................... 143 24.3 Version Compatibility, Fallbacks For Old Versions........................... 144 24.4 Share Placement............................................. 144 25 Performance costs for some common operations 145 25.1 Publishing an A-byte immutable file................................... 145 25.2 Publishing an A-byte mutable file.................................... 146 25.3 Downloading B bytes of an