gui, man, authors: Update docs, translations, and contributors

2022-10-10 04:24:03 +00:00
parent 87bf09ea40
commit fb6a35c98c
53 changed files with 410 additions and 1522 deletions
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "STDISCOSRV" "1" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "STDISCOSRV" "1" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 stdiscosrv \- Syncthing Discovery Server
 .SH SYNOPSIS
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "STRELAYSRV" "1" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "STRELAYSRV" "1" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 strelaysrv \- Syncthing Relay Server
 .SH SYNOPSIS
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-BEP" "7" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-BEP" "7" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-bep \- Block Exchange Protocol v1
 .SH INTRODUCTION AND DEFINITIONS
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-CONFIG" "5" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-CONFIG" "5" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-config \- Syncthing Configuration
 .SH SYNOPSIS
@@ -115,7 +115,7 @@ may no longer correspond to the defaults.
 .sp
 .nf
 .ft C
-<configuration version="35">
+<configuration version="37">
    <folder id="default" label="Default Folder" path="/Users/jb/Sync/" type="sendreceive" rescanIntervalS="3600" fsWatcherEnabled="true" fsWatcherDelayS="10" ignorePerms="false" autoNormalize="true">
        <filesystemType>basic</filesystemType>
        <device id="S7UKX27\-GI7ZTXS\-GC6RKUA\-7AJGZ44\-C6NAYEB\-HSKTJQK\-KJHU2NO\-CWV7EQW" introducedBy="">
@@ -150,6 +150,8 @@ may no longer correspond to the defaults.
        <junctionsAsDirs>false</junctionsAsDirs>
        <syncOwnership>false</syncOwnership>
        <sendOwnership>false</sendOwnership>
+        <syncXattrs>false</syncXattrs>
+        <sendXattrs>false</sendXattrs>
    </folder>
    <device id="S7UKX27\-GI7ZTXS\-GC6RKUA\-7AJGZ44\-C6NAYEB\-HSKTJQK\-KJHU2NO\-CWV7EQW" name="syno" compression="metadata" introducer="false" skipIntroductionRemovals="false" introducedBy="">
        <address>dynamic</address>
@@ -255,6 +257,8 @@ may no longer correspond to the defaults.
            <junctionsAsDirs>false</junctionsAsDirs>
            <syncOwnership>false</syncOwnership>
            <sendOwnership>false</sendOwnership>
+            <syncXattrs>false</syncXattrs>
+            <sendXattrs>false</sendXattrs>
        </folder>
        <device id="" compression="metadata" introducer="false" skipIntroductionRemovals="false" introducedBy="">
            <address>dynamic</address>
@@ -278,7 +282,7 @@ may no longer correspond to the defaults.
 .sp
 .nf
 .ft C
-<configuration version="35">
+<configuration version="37">
    <folder></folder>
    <device></device>
    <gui></gui>
@@ -349,6 +353,8 @@ GUI.
    <junctionsAsDirs>false</junctionsAsDirs>
    <syncOwnership>false</syncOwnership>
    <sendOwnership>false</sendOwnership>
+    <syncXattrs>false</syncXattrs>
+    <sendXattrs>false</sendXattrs>
 </folder>
 .ft P
 .fi
@@ -687,6 +693,19 @@ File and directory ownership is synced when this is set to \fBtrue\fP\&. See
 File and directory ownership information is scanned when this is set to
 \fBtrue\fP\&. See /advanced/folder\-send\-ownership for more information.
 .UNINDENT
+.INDENT 0.0
+.TP
+.B syncXattrs
+File and directory extended attributes are synced when this is set to
+\fBtrue\fP\&. See /advanced/folder\-sync\-xattrs for more information.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B sendXattrs
+File and directory extended attributes are scanned and sent to other
+devices when this is set to \fBtrue\fP\&. See
+/advanced/folder\-send\-xattrs for more information.
+.UNINDENT
 .SH DEVICE ELEMENT
 .INDENT 0.0
 .INDENT 3.5
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-DEVICE-IDS" "7" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-DEVICE-IDS" "7" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-device-ids \- Understanding Device IDs
 .sp
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-EVENT-API" "7" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-EVENT-API" "7" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-event-api \- Event API
 .SH DESCRIPTION
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-FAQ" "7" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-FAQ" "7" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-faq \- Frequently Asked Questions
 .INDENT 0.0
@@ -146,13 +146,17 @@ File permissions (when supported by file system; on Windows only the
 read only bit is synchronized)
 .IP \(bu 2
 Symbolic links (synced, except on Windows, but never followed)
+.IP \(bu 2
+File or directory owners and groups (when enabled)
+.IP \(bu 2
+Extended attributes (when enabled)
+.IP \(bu 2
+POSIX or NFS ACLs (as part of extended attributes)
 .UNINDENT
 .sp
 The following are \fInot\fP synchronized;
 .INDENT 0.0
 .IP \(bu 2
-File or directory owners and Groups (not preserved)
-.IP \(bu 2
 Directory modification times (not preserved)
 .IP \(bu 2
 Hard links (followed, not preserved)
@@ -161,9 +165,9 @@ Windows junctions (synced as ordinary directories; require enabling in
 \fBthe configuration\fP on a per\-folder
 basis)
 .IP \(bu 2
-Extended attributes, resource forks (not preserved)
+Resource forks (not preserved)
 .IP \(bu 2
-Windows, POSIX or NFS ACLs (not preserved)
+Windows ACLs (not preserved)
 .IP \(bu 2
 Devices, FIFOs, and other specials (ignored)
 .IP \(bu 2
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-GLOBALDISCO" "7" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-GLOBALDISCO" "7" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-globaldisco \- Global Discovery Protocol v3
 .SH ANNOUNCEMENTS
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-LOCALDISCO" "7" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-LOCALDISCO" "7" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-localdisco \- Local Discovery Protocol v4
 .SH MODE OF OPERATION
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-NETWORKING" "7" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-NETWORKING" "7" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-networking \- Firewall Setup
 .SH ROUTER SETUP
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-RELAY" "7" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-RELAY" "7" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-relay \- Relay Protocol v1
 .SH WHAT IS A RELAY?
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-REST-API" "7" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-REST-API" "7" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-rest-api \- REST API
 .sp
@@ -43,6 +43,11 @@ the configuration file. To use an API key, set the request header
 \fBX\-API\-Key\fP to the API key value. For example, \fBcurl \-X POST \-H
 "X\-API\-Key: abc123" http://localhost:8384/rest/...\fP can be used to invoke
 with \fBcurl\fP (add \fB\-k\fP flag when using HTTPS with a Syncthing generated or self signed certificate).
+.sp
+One exception to this requirement is \fB/rest/noauth\fP, you do not need an API
+key to use those endpoints. This way third\-party devices and services can do
+simple calls that don’t expose sensitive information without having to expose
+your API key.
 .SH RESULT PAGINATION
 .sp
 Some \fIGET\fP endpoints take optional \fBpage\fP and \fBperpage\fP arguments for
@@ -1329,7 +1334,9 @@ not connected.  Otherwise it can be either \fBpaused\fP, \fBnotSharing\fP, or
 .SS GET /rest/db/file
 .sp
 Returns most data available about a given file, including version and
-availability. Takes \fBfolder\fP and \fBfile\fP parameters.
+availability. Takes \fBfolder\fP and \fBfile\fP parameters. \fBlocal\fP and
+\fBglobal\fP refer to the current file on disk and the globally newest file,
+respectively.
 .INDENT 0.0
 .INDENT 3.5
 .sp
@@ -1342,49 +1349,88 @@ availability. Takes \fBfolder\fP and \fBfile\fP parameters.
      "fromTemporary": false
    }
  ],
-  "global": {
+  "global": { /* a file entry */ },
+  "local": { /* a file entry */ }
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+A file entry looks like this:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{
+  {
    "deleted": false,
    "ignored": false,
+    "inodeChange": "1970\-01\-01T01:00:00+01:00",
    "invalid": false,
    "localFlags": 0,
-    "modified": "2018\-08\-18T12:21:13.836784059+02:00",
-    "modifiedBy": "SYNO4VL",
+    "modified": "2022\-09\-28T08:07:19.979723+02:00",
+    "modifiedBy": "523ITIE",
    "mustRescan": false,
-    "name": "testfile",
+    "name": "img",
    "noPermissions": false,
-    "numBlocks": 1,
+    "numBlocks": 0,
    "permissions": "0755",
-    "sequence": 107499,
-    "size": 1234,
-    "type": 0,
+    "platform": { /* platform specific data */ },
+    "sequence": 914,
+    "size": 128,
+    "type": "FILE_INFO_TYPE_DIRECTORY",
    "version": [
-      "SYNO4VL:1"
+      "523ITIE:1664345275"
    ]
  },
-  "local": {
-    "deleted": false,
-    "ignored": false,
-    "invalid": false,
-    "localFlags": 0,
-    "modified": "2018\-08\-18T12:21:13.836784059+02:00",
-    "modifiedBy": "SYNO4VL",
-    "mustRescan": false,
-    "name": "testfile",
-    "noPermissions": false,
-    "numBlocks": 1,
-    "permissions": "0755",
-    "sequence": 111038,
-    "size": 1234,
-    "type": 0,
-    "version": [
-      "SYNO4VL:1"
-    ]
+  "mtime": {
+    "err": null,
+    "value": {
+      "real": "0001\-01\-01T00:00:00Z",
+      "virtual": "0001\-01\-01T00:00:00Z"
+    }
  }
 }
 .ft P
 .fi
 .UNINDENT
 .UNINDENT
+.sp
+Platform specific data may be ownership, extended attributes, etc. and is
+divided into entries per operating system / platform. An example platform
+entry containing ownership information for Unix systems and an extended
+attribute for macOS (“darwin”) looks as follows:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{
+  "darwin": {
+    "xattrs": [
+      {
+        "name": "net.kastelo.xattrtest",
+        "value": "aGVsbG8="
+      }
+    ]
+  },
+  "freebsd": null,
+  "linux": null,
+  "netbsd": null,
+  "unix": {
+    "gid": 20,
+    "groupName": "staff",
+    "ownerName": "jb",
+    "uid": 501
+  },
+  "windows": null
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .SS GET /rest/db/ignores
 .sp
 Takes one parameter, \fBfolder\fP, and returns the content of the
@@ -1981,6 +2027,24 @@ $ curl \-H X\-API\-Key:... "http://localhost:8384/rest/debug/file?folder=default
 .sp
 The returned object contains the same info as db\-file\-get, plus a summary
 of \fBglobalVersions\fP\&.
+.SH NOAUTH ENDPOINTS
+.sp
+Calls that do not require authentication.
+.SS GET /rest/noauth/health
+.sp
+Returns a \fB{"status": "OK"}\fP object.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+{
+  "status": "OK"
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
 .SH AUTHOR
 The Syncthing Authors
 .SH COPYRIGHT
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-SECURITY" "7" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-SECURITY" "7" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-security \- Security Principles
 .sp
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-STIGNORE" "5" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-STIGNORE" "5" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-stignore \- Prevent files from being synchronized to other nodes
 .SH SYNOPSIS
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING-VERSIONING" "7" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING-VERSIONING" "7" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing-versioning \- Keep automatic backups of deleted files by other nodes
 .sp
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "SYNCTHING" "1" "Sep 14, 2022" "v1.21.0" "Syncthing"
+.TH "SYNCTHING" "1" "Oct 07, 2022" "v1.22.0" "Syncthing"
 .SH NAME
 syncthing \- Syncthing
 .SH SYNOPSIS