diff --git a/README.md b/README.md index 79ea84b3..5ebebc3a 100644 --- a/README.md +++ b/README.md @@ -25,178 +25,11 @@ making sure large swarms of selfish agents behave and somehow work towards a common goal. Here we have a much smaller swarm of cooperative agents and a simpler approach will suffice. -Features --------- +Documentation +============= -> To request features and file bugs, see [the issue tracker][issues]. - -The following features are _currently implemented and working_: - - * The formation of a cluster of nodes, certificate authenticated and - communicating over TLS over TCP. - - * Synchronization of a single directory among the cluster nodes. - - * Change detection by periodic scanning of the local repository. - - * Static configuration of cluster nodes. - - * Automatic discovery of cluster nodes. See [discover.go][discover.go] - for the protocol specification. Discovery on the LAN is performed by - broadcasts, Internet wide discovery is performed with the assistance - of a global server. - - * Handling of deleted files. Deletes can be propagated or ignored per - client. - - * Synchronizing multiple unrelated directory trees by following - symlinks directly below the repository level. - - * HTTP GUI. - -The following features are _not yet implemented but planned_: - - * Change detection by listening to file system notifications instead of - periodic scanning. - -The following features are _not implemented but may be implemented_ in -the future: - - * Syncing multiple directories from the same syncthing instance. - - * Automatic NAT handling via UPNP. - - * Conflict resolution. Currently whichever file has the newest - modification time "wins". The correct behavior in the face of - conflicts is open for discussion. - -[discover.go]: https://github.com/calmh/syncthing/blob/master/discover/discover.go -[issues]: https://github.com/calmh/syncthing/issues - -Security --------- - -Security is one of the primary project goals. This means that it should -not be possible for an attacker to join a cluster uninvited, and it -should not be possible to extract private information from intercepted -traffic. Currently this is implemented as follows. - -All traffic is protected by TLS. To prevent uninvited nodes from joining -a cluster, the certificate fingerprint of each node is compared to a -preset list of acceptable nodes at connection establishment. The -fingerprint is computed as the SHA-1 hash of the certificate and -displayed in BASE32 encoding to form a compact yet convenient string. -Currently SHA-1 is deemed secure against preimage attacks. - -Incoming requests for file data are verified to the extent that the -requested file name must exist in the local index and the global model. - -Installing -========== - -Download the appropriate precompiled binary from the -[releases](https://github.com/calmh/syncthing/releases) page. Untar and -put the `syncthing` binary somewhere convenient in your `$PATH`. - -If you are a developer and have Go 1.2 installed you can also install -the latest version from source. `go get` works as expected but builds -a binary without GUI capabilities. Use the included `build.sh` script -without parameters to build a syncthing with GUI. - -Usage -===== - -Check out the options: - -``` -$ syncthing --help -Usage: - syncthing [options] - -... -``` - -Run syncthing to let it create it's config directory and certificate: - -``` -$ syncthing -11:34:13 main.go:85: INFO: Version v0.1-40-gbb0fd87 -11:34:13 tls.go:61: OK: Created TLS certificate file -11:34:13 tls.go:67: OK: Created TLS key file -11:34:13 main.go:66: INFO: My ID: NCTBZAAHXR6ZZP3D7SL3DLYFFQERMW4Q -11:34:13 main.go:90: FATAL: No config file -``` - -Take note of the "My ID: ..." line. Perform the same operation on -another computer to create another node. Take note of that ID as well, -and create a config file `~/.syncthing/syncthing.ini` looking something -like this: - -``` -[repository] -dir = /Users/jb/Synced - -[nodes] -NCTBZAAHXR6ZZP3D7SL3DLYFFQERMW4Q = 172.16.32.1:22000 192.23.34.56:22000 -CUGAE43Y5N64CRJU26YFH6MTWPSBLSUL = dynamic -``` - -This assumes that the first node is reachable on either of the two -addresses listed (perhaps one internal and one port-forwarded external) -and that the other node is not normally reachable from the outside. Save -this config file, identically, to both nodes. - -If the nodes are running on the same network, or reachable on port 22000 -from the outside world, you can set all addresses to "dynamic" and they -will find each other using automatic discovery. (This discovery, -including port numbers, can be tweaked or disabled using command line -options.) - -Start syncthing on both nodes. For the cautious, one side can be set to -be read only. - -``` -$ syncthing --ro -13:30:55 main.go:85: INFO: Version v0.1-40-gbb0fd87 -13:30:55 main.go:102: INFO: My ID: NCTBZAAHXR6ZZP3D7SL3DLYFFQERMW4Q -13:30:55 main.go:149: INFO: Initial repository scan in progress -13:30:59 main.go:153: INFO: Listening for incoming connections -13:30:59 main.go:157: INFO: Attempting to connect to other nodes -13:30:59 main.go:247: INFO: Starting local discovery -13:30:59 main.go:165: OK: Ready to synchronize -13:31:04 discover.go:113: INFO: Discovered node CUGAE43Y5N64CRJU26YFH6MTWPSBLSUL at 172.16.32.24:22000 -13:31:14 main.go:296: INFO: Connected to node CUGAE43Y5N64CRJU26YFH6MTWPSBLSUL -13:31:19 main.go:345: INFO: Transferred 139 KiB in (14 KiB/s), 139 KiB out (14 KiB/s) -13:32:20 model.go:94: INFO: CUGAE43Y5N64CRJU26YFH6MTWPSBLSUL: 263.4 KB/s in, 69.1 KB/s out -13:32:20 model.go:104: INFO: 18289 files, 24.24 GB in cluster -13:32:20 model.go:111: INFO: 17132 files, 22.39 GB in local repo -13:32:20 model.go:117: INFO: 1157 files, 1.84 GB to synchronize -... -``` -You should see the synchronization start and then finish a short while -later. Add nodes to taste. - -GUI ---- - -The web based GUI is disabled per default. To enable and access it you -must start syncthing with the `--gui` command line option, giving a -listen address. For example: - -``` -$ syncthing --gui 127.0.0.1:8080 -``` - -You then point your browser to the given address. - -Excluding Files ---------------- - -syncthing looks for files named `.stignore` while walking the -repository. The file is expected to contain glob patterns of file names -to ignore. Patterns are matched on file name only and apply to files in -the same directory as the `.stignore` file and in directories lower down -in the hierarchy. +The syncthing documentation is kept on the +[GitHub Wiki](https://github.com/calmh/syncthing/wiki). License =======