felixfoertsch/syncthing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 10 Wiki Activity

Initial

Browse Source
This commit is contained in:
Jakob Borg
2015-05-28 12:40:43 +02:00
commit fd7fe795ad
92 changed files with 4050 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dev/building.rst
+173
View File
@@ -0,0 +1,173 @@
Building Syncthing
==================
.. note::
You probably only need to go through the build process if you are going
to do development on syncthing or if you need to do a special packaging
of it. For all other purposes we recommend using the the official binary
releases instead.
.. note::
If you're on Linux and want the quickest possible start, check out
:ref:`building-with-docker`. Otherwise follow the guide below to set up the
development environment on your computer.
Branches and Tags
-----------------
You should base your work on the ``master`` branch when doing your
development. This branch is usually what will be going into the next
release and always what pull requests should be based on.
If you're looking to build and package a release of syncthing you should
instead use the latest tag (``vX.Y.Z``) as the contents of ``master``
may be unstable and unsuitable for general consumption.
Prerequisites
-------------
- Go **1.3** or higher
- Git
If you're not a Go developer since before, the easiest way to get going
is to download the latest version of Go as instructed in
http://golang.org/doc/install and ``export GOPATH=~``.
Building (Unix)
---------------
- Install the prerequisites.
- Open a terminal.
.. code:: bash
# This should output "go version go1.3" or higher.
$ go version
# Go is particular about file locations; use this path unless you know very
# well what you're doing.
$ mkdir -p ~/src/github.com/syncthing
$ cd ~/src/github.com/syncthing
# Note that if you are building from a source code archive, you need to
# rename the directory from syncthing-XX.YY.ZZ to syncthing
$ git clone https://github.com/syncthing/syncthing
# Now we have the source. Time to build!
$ cd syncthing
# You should be inside ~/src/github.com/syncthing/syncthing right now.
$ go run build.go
Unless something goes wrong, you will have a ``syncthing`` binary built
and ready in ``~/src/github.com/syncthing/syncthing/bin``.
Building (Windows)
------------------
- Install the prerequisites.
- Open a ``cmd`` Window.
.. code:: bash
# This should output "go version go1.3" or higher.
> go version
# Go is particular about file locations; use this path unless you know very
# well what you're doing.
> mkdir c:\src\github.com\syncthing
> cd c:\src\github.com\syncthing
# Note that if you are building from a source code archive, you need to
# rename the directory from syncthing-XX.YY.ZZ to syncthing
> git clone https://github.com/syncthing/syncthing
# Now we have the source. Time to build!
> cd syncthing
> go run build.go
Unless something goes wrong, you will have a ``syncthing.exe`` binary
built and ready in ``c:\src\github.com\syncthing\syncthing\bin``.
Subcommands and Options
-----------------------
The following ``build.go`` subcommands and options exist.
- ``go run build.go install`` -- installs binaries in ``./bin``
(default command, this is what happens when build.go is run without
any commands or parameters).
- ``go run build.go build`` -- forces a rebuild of the binary to the
current directory; similar to ``install`` but slower.
- ``go run build.go clean`` -- remove build artefacts, guaranteeing a
complete rebuild. Use this when switching between normal builds and
noupgrade builds.
- ``go run build.go test`` -- run the tests.
- ``go run build.go tar`` -- create a syncthing tar.gz dist file in the
current directory. Assumes a Unixy build.
- ``go run build.go zip`` -- create a syncthing zip dist file in the
current directory. Assumes a Windows build.
- ``go run build.go assets`` -- rebuild the compiled-in GUI assets.
- ``go run build.go deps`` -- update the in-repo dependencies.
- ``go run build.go xdr`` -- regenerate the XDR en/decoders. Only
necessary when the protocol has changed.
The options ``-no-upgrade``, ``-goos`` and ``-goarch`` can be given to
influence ``install``, ``build``, ``tar`` and ``zip``. Examples:
- ``go run build.go -goos linux -goarch 386 tar`` -- build a tar.gz
distribution of syncthing for linux-386.
- ``go run build.go -goos windows -no-upgrade zip`` -- build a zip
distribution of syncthing for Windows (current architecture) with
upgrading disabled.
Building without Git
--------------------
Syncthing can be built perfectly fine from a source tarball of course.
If the tarball is from our build server it contains a file called
``RELEASE`` that information the build system of the version being
build. If you're building from a different source package, for example
one automatically generated by Github, you must instead pass the
``-version`` flag to ``build.go``.
If you are building something that will be installed as a package
(Debian, RPM, ...) you almost certainly want to use ``-no-upgrade`` as
well to prevent the built in upgrade system from being activated.
- ``go run build.go -version v0.10.26 -no-upgrade tar`` -- build a
tar.gz distribution of syncthing for the current OS/arch, tagged as
``v0.10.26``, with upgrades disabled.
.. _building-with-docker:
Building with Docker
--------------------
The Docker based build image exactly replicates the official build
process and is a quick way to get up and running with the full cross
compiled setup. Start by getting the build image. It is fairly large
(about 2 GiB).
::
$ docker pull syncthing/build:latest
Then check out and build Syncthing.
::
$ git clone https://github.com/syncthing/syncthing
$ cd syncthing
$ ./build.sh docker-all
A full build is done for all supported architectures, and tests are run.
The process should end with a bunch of release files (``.tar.gz`` and
``.zip``) created.
dev/debugging.rst
+130
View File
@@ -0,0 +1,130 @@
Debugging Syncthing
===================
There's a lot that happens behind the covers, and syncthing is generally
quite silent about it. A number of environment variables can be used to
set the logging to verbose for various parts of the program, and to
enable profiling.
Environment Variables
---------------------
STTRACE
~~~~~~~
The environment variable ``STTRACE`` can be set to a comma separated
list of "facilities", to enable extra debugging information for said
facility. A facility generally maps to a Go package, although there are
a few extra that map to parts of the ``main`` package. Currently, the
following facilities are supported (an up to date list is always printed
by ``syncthing --help``):
- ``beacon`` (the beacon package)
- ``discover`` (the discover package)
- ``events`` (the events package)
- ``files`` (the files package)
- ``http`` (the main package; HTTP requests)
- ``net`` (the main package; connections & network messages)
- ``model`` (the model package)
- ``scanner`` (the scanner package)
- ``stats`` (the stats package)
- ``upnp`` (the upnp package)
- ``xdr`` (the xdr package)
- ``all`` (all of the above)
The debug output is often of the kind that it doesn't make much sense
without looking at the code. The purpose of the different packages /
facilities are something like this:
- ``beacon`` sends and receives UDP broadcasts used by the local
discovery system. Debugging here will show which interfaces and
addresses are selected for broadcasts, etc.
- ``discover`` sends and received local discovery packets. Debugging
here will output the parsed packets, nodes that get registered etc.
- ``files`` keeps track of lists of files with metadata and figures out
which is the newest version of each.
- ``net`` shows connection attempts, incoming connections, and the low
level error when connection attempts fail.
- ``model`` is the largest chunk of the system; this is where pulling
of out of date files happen, indexes sent and received, and incoming
requests for file chunks are logged.
- ``scanner`` is the local filesystem scanner. Debugging here will
output information about changed and unchanged files.
- ``upnp`` is the upnp talker.
- ``xdr`` is the low level protocol encoder. Debugging here will output
all bytes sent/received over the sync connection. Very verbose.
- ``all`` simply enabled debugging of all facilities.
Enabling any of the facilities will also change the log format to
include microsecond timestamps and file names plus line numbers. This
can be used to enable this extra information on the normal logging
level, without enabling any debugging: ``STTRACE=somethingnonexistent``
for example.
Under Unix (including Mac) the easiest way to run syncthing with an
environment variable set is to prepend the variable to the command line.
I.e:
``$ STTRACE=model syncthing``
On windows, it needs to be set prior to running syncthing.
::
C:\> set STTRACE=model
C:\> syncthing
STPROFILER
~~~~~~~~~~
The ``STPROFILER`` environment variable sets the listen address for the
HTTP profiler. If set to for example ``:9090`` the profiler will start
and listen on port 9090. http://localhost:9090/debug/pprof is then the
address to the profiler. Se ``go tool pprof`` for more information.
STGUIASSETS
~~~~~~~~~~~
Directory to load GUI assets from. Overrides compiled in assets. Useful
for developing webgui, commonly use ``STGUIASSETS=gui bin/syncthing``
STCPUPROFILE
~~~~~~~~~~~~
Write a CPU profile to ``cpu-$pid.pprof`` on exit.
STHEAPPROFILE
~~~~~~~~~~~~~
Write heap profiles to ``heap-$pid-$timestamp.pprof`` each time
heap usage increases.
STBLOCKPROFILE
~~~~~~~~~~~~~~
Write block profiles to ``block-$pid-$timestamp.pprof`` every 20
seconds.
STPERFSTATS
~~~~~~~~~~~
Write running performance statistics to ``perf-$pid.csv``. Not supported on
Windows.
STNOUPGRADE
~~~~~~~~~~~
Disable automatic upgrades.
GOMAXPROCS
~~~~~~~~~~
Set the maximum number of CPU cores to use. Defaults to all available
CPU cores.
GOGC
~~~~
Percentage of heap growth at which to trigger GC. Default is 100. Lower
numbers keep peak memory usage down, at the price of CPU usage (ie.
performance)
dev/device-ids.rst
+237
View File
@@ -0,0 +1,237 @@
########################
Understanding Device IDs
########################
Every device is identified by a device ID. The device ID is used for
address resolution, authentication and authorization. The term "device
ID" could interchangably have been "key ID" since the device ID is a
direct properties of the public key in use.
Keys
====
To understand device IDs we need to look at the underlying mechanisms.
At first startup, syncthing will create an public/private key pair.
Currently this is a 3072 bit RSA key. The keys are saved in the form of
the private key (``key.pem``) and a self signed certificate
(``cert.pem``). The self signing part doesn't actually add any security
or functionality as far as syncthing is concerned but it enables the use
of the keys in a standard TLS exchange.
The typical certificate will look something like this, inspected with
``openssl x509``:
::
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 0 (0x0)
Signature Algorithm: sha1WithRSAEncryption
Issuer: CN=syncthing
Validity
Not Before: Mar 30 21:10:52 2014 GMT
Not After : Dec 31 23:59:59 2049 GMT
Subject: CN=syncthing
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
RSA Public Key: (3072 bit)
Modulus (3072 bit):
00:da:83:8a:c0:95:af:0a:42:af:43:74:65:29:f2:
30:e3:b9:12:d2:6b:70:93:da:0b:7b:8a:1e:e5:79:
...
99:09:4c:a9:7b:ba:4a:6a:8b:3b:e6:e7:c7:2c:00:
90:aa:bc:ad:94:e7:80:95:d2:1b
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Key Usage: critical
Digital Signature, Key Encipherment
X509v3 Extended Key Usage:
TLS Web Server Authentication, TLS Web Client Authentication
X509v3 Basic Constraints: critical
CA:FALSE
Signature Algorithm: sha1WithRSAEncryption
68:72:43:8b:83:61:09:68:f0:ef:f0:43:b7:30:a6:73:1e:a8:
d9:24:6c:2d:b4:bc:c9:e8:3e:0b:1e:3c:cc:7a:b2:c8:f1:1d:
...
88:7e:e2:61:aa:4c:02:e3:64:b0:da:70:3a:cd:1c:3d:86:db:
df:54:b9:4e:be:1b
We can see here that the certificate is little more than a container for
the public key; the serial number is zero and the Issuer and Subject are
both "syncthing" where a qualified name might otherwise be expected.
An advanced user could replace the ``key.pem`` and ``cert.pem`` files
with a keypair generated directly by the ``openssl`` utility or other
mechanism.
Device IDs
==========
To form a device ID the SHA-256 hash of the certificate data in DER form
is calculated. This means the hash covers all information under the
``Certificate:`` section above.
The hashing results in a 256 bit hash, which we encode using base32.
Base32 encodes five bits per character, so we need 256 / 5 = 51.2
characters to encode the device ID. This becomes 52 characters in
practice, but 52 characters of base32 would decode to 260 bits which is
not an whole number of bytes. The base32 encoding adds padding to 280
bits (the next multiple of both 5 and 8 bits) so the resulting ID looks
something like
``MFZWI3DBONSGYYLTMRWGC43ENRQXGZDMMFZWI3DBONSGYYLTMRWA====``.
The padding (``====``) is stripped away, the device ID split in four
groups, and `check
digits <https://forum.syncthing.net/t/v0-9-0-new-device-id-format/478>`__
are added for each group. For presentation purposes the device ID is
grouped with dashes, resulting in the final value:
``MFZWI3D-BONSGYC-YLTMRWG-C43ENR5 -QXGZDMM-FZWI3DP-BONSGYY-LTMRWAD``.
Connection Establishment
========================
So now we know what device IDs are, here's how they are used in
syncthing. When you add a device ID to the syncthing configuration,
syncthing will attempt to connect to that device. The first thing we
need to do is figure out the IP and port to connect to. There's three
possibilities here;
- The IP and port can be set statically in the configuration. The IP
can equally well be a hostname, so if you have a static IP or a
dynamic DNS setup this might be a good option.
- Using local discovery, if enabled. Every syncthing instance on a LAN
periodically broadcasts information about itself (device ID, address,
port number). If we've seen one of these broadcasts for a given
device ID that's where we try to connect.
- Using global discovery, if enabled. Every syncthing instance
announces itself to the global discovery service (device ID and
external port number - the internal address is not announced to the
global server). If we don't have a static address and haven't seen
any local announcements the global discovery server will be queried
for an address.
Once we have and address and port a TCP connection is established and a
TLS handshake performed. As part of the handshake both devices present
their certificates. Once the handshake has completed and the peer
certificiate is known, the following steps are performed.
1. Calculate the remote device ID by using the process above on the
received certificate.
2. Weed out a few possible misconfigurations - i.e. if the device ID is
that of the local device or of a device we already have an active
connection to. Drop the connection in these cases.
3. Verify the remote device ID against the configuration. If it is not a
device ID we are expecting to talk to, drop the connection.
4. Verify the certificate ``CommonName`` against the configuration. By
default, we expect it to be ``syncthing``, but when using custom
certificates this can be changed.
5. If everything checks out so far, accept the connection.
An Aside About Collisions
-------------------------
The SHA-256 hash is cryptographically collision resistant. This means
that there is no way that we know of to create two different messages
with the same hash.
You can argue that of course there are collisions - there's an infinite
amount of inputs and a finite amount of outputs, so per definition there
are infinitely many messages that result in the same hash.
I'm going to quote `stack
overflow <http://stackoverflow.com/questions/4014090/is-it-safe-to-ignore-the-possibility-of-sha-collisions-in-practice>`__
here:
The usual answer goes thus: what is the probability that a rogue
asteroid crashes on Earth within the next second, obliterating
civilization-as-we- know-it, and killing off a few billion people ?
It can be argued that any unlucky event with a probability lower
than that is not actually very important.
If we have a "perfect" hash function with output size n, and we have
p messages to hash (individual message length is not important),
then probability of collision is about p2/2n+1 (this is an
approximation which is valid for "small" p, i.e. substantially
smaller than 2n/2). For instance, with SHA-256 (n=256) and one
billion messages (p=10^9) then the probability is about 4.3\*10^-60.
A mass-murderer space rock happens about once every 30 million years
on average. This leads to a probability of such an event occurring
in the next second to about 10^-15. That's 45 orders of magnitude
more probable than the SHA-256 collision. Briefly stated, if you
find SHA-256 collisions scary then your priorities are wrong.
It's also worth noting that the property of SHA-256 that we are using is
not simply collision resistance but resistance to a preimage attack.
I.e. even if you can find two messages that result in a hash collision
that doesn't help you attack syncthing (or TLS in general). You need to
create a message that hashes to exactly the hash that my certificate
already has or you won't get in.
Note also that it's not good enough to find a random blob of bits that
happen to have the same hash as my certificate. You need to create a
valid DER- encoded, signed certificate that has the same hash as mine.
The difficulty of this is staggeringly far beyond the already staggering
difficulty of finding a SHA-256 collision.
Problems and Vulnerabilities
============================
As far as I know, these are the issues or potential issues with the
above mechanism.
Discovery Spoofing
------------------
Currently, neither the local nor global discovery mechanism is protected
by crypto. This means that any device can in theory announce itself for
any device ID and potentially receive connections for that device.
This could be a denial of service attack (we can't find the real device
for a given device ID, so can't connect to it and sync). It could also
be an intelligence gathering attack; if I spoof a given ID, I can see
which devices try to connect to it.
It could be mitigated in several ways;
- Announcements could be signed by the device private key. This
requires already having the public key to verify.
- Announcements to the global announce server could be done using TLS,
so the server calculates the device ID based on the certificate
instead of trusting to the device to tell the truth.
- The user could statically configure IP or hostname for the devices.
- The user could run a trusted global server.
It's something we might want to look at at some point, but not a huge
problem as I see it.
Long Device IDs are Painful
---------------------------
It's a mouthful to read over the phone, annoying to type into an SMS or
even into a computer. And it needs to be done twice, once for each side.
This isn't a vulnerability as such, but a user experience problem. There
are various possible solutions;
- Use shorter device IDs with verification based on the full ID ("You
entered MFZWI3; I found and connected to a device with the ID
MFZWI3-DBONSG-YYLTMR-WGC43E-NRQXGZ-DMMFZW-I3DBON-SGYYLT-MRWA, please
confirm that this is correct.").
- Use shorter device IDs with an out of band authentication, a la
Bluetooth pairing. You enter a one time PIN into syncthing and give
that PIN plus a short device ID to another user. On initial connect,
both sides verify that the other knows the correct PIN before
accepting the connection.
dev/events.rst
+53
View File
@@ -0,0 +1,53 @@
Event API
=========
Syncthing provides a simple long polling interface for exposing events from
the core utility towards a GUI.
To receive events, perform a HTTP GET of ``/rest/events?since=<lastSeenID>``,
where ``<lastSeenID>`` is the ID of the last event you've already seen or zero.
Syncthing returns a JSON encoded array of event objects, starting at the event
just after the one with the last seen ID. There is a limit to the number of
events buffered, so if the rate of events is high or the time between polling
calls is long some events might be missed. This can be detected by noting a
discontinuity in the event IDs.
If no new events are produced since ``<lastSeenID>``, the HTTP call blocks and
waits for new events to happen before returning, or if no new events are
produced within 60 seconds, times out.
To receive only a limited number of events, add the ``limit=n`` parameter with a
suitable value for ``n`` and only the *last* ``n`` events will be returned. This
can be used to catch up with the latest event ID after a disconnection for
example: ``/rest/events?since=0&limit=1``.
Event Structure
---------------
Each event is represented by an object similar to the following::
{
"id": 2,
"type": "DeviceConnected",
"time": "2014-07-13T21:04:33.687836696+02:00",
"data": {
"addr": "172.16.32.25:22000",
"id": "NFGKEKE-7Z6RTH7-I3PRZXS-DEJF3UJ-FRWJBFO-VBBTDND-4SGNGVZ-QUQHJAG"
}
}
The top level keys ``id``, ``time``, ``type`` and ``data`` are always present, though ``data`` may be ``null``.
* ``id`` is a monotonically increasing integer. The first event generated has id ``1``, the next has id ``2`` etc.
* ``time`` is the time the event was generated.
* ``type`` indicates the type of (i.e. reason for) the event and is one of the event types below.
* ``data`` is an object containing optional extra information; the exact structure is determined by the event type.
Events
------
.. toctree::
:maxdepth: 2
:glob:
../events/*
dev/issues.rst
+50
View File
@@ -0,0 +1,50 @@
Issue Management
================
Bugs, feature requests and other things we need to do are tracked as
Github issues. Issues can be of various types and in various states, and
also belong to milestones or not. This page is an attempt to document
the current practice.
Labels
------
Issues without labels are undecided - that is, we don't yet know if it's
a bug, a configuration issue, a feature request or what. Issues that are
invalid for whatever reason are closed with a short explanation of why.
Examples include "Duplicate of #123", "Discovered to be configuration
error", "Rendered moot by #123" and so on. We don't use the "invalid" or
"wontfix" labels.
- **android** - Marks an issue as occurring on the Android platform
only.
- **bug** - The issue is a verified bug.
- **build** - The issue is caused by or requires changes to the build
system (scripts or Docker image).
- **docs** - Something requires documenting.
- **easy** - This could be easily fixed, probably an hours work or
less.
- **enhancement** - This is a new feature or an improvement of some
kind, as opposed to a problem (bug).
- **help-wanted** - The core team can't or won't do this, but someone
else is welcome to. This does not mean that help is not wanted on the
*other* issues. You can see this as a soft ``wontfix``.
- **pr-bugfix** - This pull request *fixes* a bug. This is different
from the ``bug`` label, as there may also be pull requests with for
example tests that *prove* a bug which would then be labeled ``bug``.
- **pr-refactor** - This pull request is a refactoring, i.e. not
supposed to change behavior.
- **pr-wait-or-pending** - This pull request is not ready for merging,
even if the tests pass and it looks good. It is incomplete or
requires more discussion.
- **protocol** - This requires a change to the protocol.
dev/jenkins.rst
+35
View File
@@ -0,0 +1,35 @@
Interacting with Jenkins
========================
Jenkins will test pull requests from recognized authors. If the pull
request is not from a recognized author, an *admin* needs to tell
Jenkins to perform the tests, after giving the patch a manual look over
to prevent shenanigans. A number of tests are performed, ranging from
verifying correct code formatting and that the author is included in the
AUTHORS file to that the code in fact builds and passes tests. A pull
request should usually only be merged if all tests return green,
although there are exceptions.
To enable testing for this pull request only:
::
@st-jenkins ok to test
To enable testing for this pull request, and all future pull requests
from the same author:
::
@st-jenkins add to whitelist
For pull requests where Jenkins has already run it's tests, but should
run them again:
::
@st-jenkins test this please
This is not necessary when new commits are pushed (tests will be rerun
for the new commits), but is useful if something has changed server side
or to verify that everything is still OK if ``master`` has been updated.
dev/release-schedule.rst
+45
View File
@@ -0,0 +1,45 @@
Release Schedule
================
Structure
---------
Syncthing follows the `Semantic Versioning <http://semver.org/>`__
scheme of versioning. Each release has a three part version number:
*major*.\ *minor*.\ *patch*.
A new *major* version is released when there are incompatible API or
protocol changes, a new *minor* version is released when there are new
features but compatibility with older releases is retained, and a new
*patch* version is released when there are bug fixes (compatibility with
older releases always retained).
While still in pre-release mode, i.e. versions 0.\ *x*, breaking changes
are made in minor releases rather than major. Version 0.7.3 should be
able to talk to version 0.7.52, but will probably not understand version
0.8.0. This also means that if you don't like 0.7.52, you can safely
downgrade to 0.7.3 again and keep your configuration, index caches, etc.
However 0.8.0 might have a different format for those things so a
downgrade to 0.7.x might be trickier.
Patch Releases
--------------
A new patch release is made each sunday, if there have been changes
committed since the last release. Serious bugs, such as would crash the
client or corrupt data, cause an immediate (out of schedule) patch
release.
Minor Releases
--------------
Minor releases are made when new functionality is ready for release.
This happen approximately once every few weeks, with the pace slowing as
the 1.0 release nears.
Major Releases
--------------
A new major release is a rare event. At the time of writing this has not
yet happened and is foreseen to happen only once in the foreseeable
future - the 1.0 release.
dev/release.rst
+53
View File
@@ -0,0 +1,53 @@
Creating a Release
==================
Prerequisites
-------------
- Push access to the syncthing repo, for pushing a new tag.
- SSH account on build server, member of the ``jenkins`` group, for
accessing and signing the releases.
- The release signing key on your GPG keyring on your own computer (for
signing the tag) and your account on the build server (for signing
the release). In a pinch, having it just on the build server will do
since you can run git there to create, sign and push the tag.
- Your Github token in the ``GITHUB_TOKEN`` environment variable on the
build server, for uploading the release.
Process
-------
Make sure the build seems sane. I.e. the build is clean on the build
server, the integration tests pass without complaints. (Currently, the
tests are a bit flaky, specifically the ``TestSyncCluster...`` ones. I'm
not sure if the tests are weird or there is something actually bad
happening that should be fixed - requires investigation).
Create a new, signed tag on master, with the version as comment, and
push it:
.. code:: bash
$ git tag -a -s -u release@syncthing.net -m v0.10.15 v0.10.15
$ git push --tags
The build server will build packages under the job
``syncthing-release``. Wait for this to complete successfully before
moving on.
Run ``./changelog.sh`` (in the repo) to create the changelog comparison
from the previous release. Copy to clipboard.
On the Github releases page, select the newly pushed tag and hit "Edit
Tag". Set the "Release title" to the same version as the tag, paste in
the changelog from above, and publish the release.
On the build server, logged in via ssh, run
``/usr/local/bin/upload-release``. This will create the md5sum and
sha1sum files, sign them (gpg will prompt for key passphrase twice) and
upload the whole shebang to Github.
Verify it looks sane on the releases page.
dev/rest.rst
+52
View File
@@ -0,0 +1,52 @@
REST API
========
Syncthing exposes a REST interface over HTTP on the GUI port. This is
used by the GUI code (Javascript) and can be used by other processes
wishing to control syncthing. In most cases both the input and output
data is in JSON format. The interface is subject to change.
API Key
-------
To use the POST methods, or *any* method when authentication is enabled,
an API key must be set and used. The API key can be generated in the
GUI, or set in the ``configuration/gui/apikey`` element in the
configuration file. To use an API key, set the request header
``X-API-Key`` to the API key value.
System Endpoints
----------------
.. toctree::
:maxdepth: 1
:glob:
../rest/system-*
Database Endpoints
------------------
.. toctree::
:maxdepth: 1
:glob:
../rest/db-*
Statistics Endpoints
--------------------
.. toctree::
:maxdepth: 1
:glob:
../rest/stats-*
Misc Services Endpoints
-----------------------
.. toctree::
:maxdepth: 1
:glob:
../rest/svc-*