diff --git a/gui/default/assets/lang/lang-ko-KR.json b/gui/default/assets/lang/lang-ko-KR.json index 75f35c10..bffbb2da 100644 --- a/gui/default/assets/lang/lang-ko-KR.json +++ b/gui/default/assets/lang/lang-ko-KR.json @@ -3,7 +3,7 @@ "A negative number of days doesn't make sense.": "음수로는 지정할 수 없습니다.", "A new major version may not be compatible with previous versions.": "새로운 메이저 버전은 이전 버전과 호환되지 않을 수 있습니다.", "API Key": "API 키", - "About": " 정보", + "About": "정보", "Actions": "동작", "Add": "추가", "Add Device": "기기 추가", diff --git a/gui/default/assets/lang/lang-pt-BR.json b/gui/default/assets/lang/lang-pt-BR.json index 89af86fb..27823471 100644 --- a/gui/default/assets/lang/lang-pt-BR.json +++ b/gui/default/assets/lang/lang-pt-BR.json @@ -60,7 +60,7 @@ "Enable Relaying": "Habilitar retransmissão", "Enable UPnP": "Habilitar UPnP", "Enter comma separated (\"tcp://ip:port\", \"tcp://host:port\") addresses or \"dynamic\" to perform automatic discovery of the address.": "Insira endereços (\"tcp://ip:porta\", \"tcp://host:porta\") separados por vírgula ou \"dynamic\" para executar a descoberta automática do endereço.", - "Enter ignore patterns, one per line.": "Insira os padrões de exclusão, um por linha.", + "Enter ignore patterns, one per line.": "Insira os filtros, um por linha.", "Error": "Erro", "External File Versioning": "Versionamento externo de arquivo", "Failed Items": "Itens com falha", @@ -89,7 +89,7 @@ "Help": "Ajuda", "Home page": "Página inicial", "Ignore": "Ignorar", - "Ignore Patterns": "Padrões de exclusão", + "Ignore Patterns": "Filtros", "Ignore Permissions": "Ignorar permissões", "Incoming Rate Limit (KiB/s)": "Limite de velocidade de recepção (KiB/s)", "Incorrect configuration may damage your folder contents and render Syncthing inoperable.": "A configuração incorreta poderá causar danos aos seus dados e tornar o Syncthing inoperante.", diff --git a/gui/default/assets/lang/lang-sv.json b/gui/default/assets/lang/lang-sv.json index 0ef50243..8c1d5ae0 100644 --- a/gui/default/assets/lang/lang-sv.json +++ b/gui/default/assets/lang/lang-sv.json @@ -1,6 +1,6 @@ { - "A device with that ID is already added.": "En enhet med det ID är redan tillagt.", - "A negative number of days doesn't make sense.": "Ett negativt antal dagar är inte troligt.", + "A device with that ID is already added.": "En enhet med det ID:t är redan tillagt.", + "A negative number of days doesn't make sense.": "Ett negativt antal dagar är inte rimligt.", "A new major version may not be compatible with previous versions.": "En ny huvudversion kan eventuellt vara inkompatibel med tidigare versioner.", "API Key": "API-nyckel", "About": "Om", @@ -19,51 +19,51 @@ "Allow Anonymous Usage Reporting?": "Tillåt anonym användarstatistiksrapportering?", "Alphabetic": "Alfabetisk", "An external command handles the versioning. It has to remove the file from the synced folder.": "Ett externt kommando sköter versionshanteringen. Det måste ta bort filen från den synkroniserade mappen.", - "Anonymous Usage Reporting": "Anonym användarstatistik", + "Anonymous Usage Reporting": "Anonym användarstatistik rapportering", "Any devices configured on an introducer device will be added to this device as well.": "Enheter konfigurerade på en introduktörsenhet kommer också att läggas till den här enheten.", "Automatic upgrades": "Automatiska uppgraderingar", "Be careful!": "Var aktsam!", "Bugs": "Buggar", - "CPU Utilization": "CPU-användning", + "CPU Utilization": "CPU användning", "Changelog": "Ändringslogg", "Clean out after": "Rensa efteråt", "Close": "Stäng", "Command": "Kommando", - "Comment, when used at the start of a line": "Kommentar, vid början av en rad.", + "Comment, when used at the start of a line": "Kommentar, vid användning i början av en rad.", "Compression": "Komprimering", "Connection Error": "Anslutningsproblem", "Connection Type": "Anslutningstyp", "Copied from elsewhere": "Kopierat utifrån", - "Copied from original": "Oförändrat", - "Copyright © 2014-2016 the following Contributors:": "Copyright © 2014-2016 följande bidragande:", + "Copied from original": "Kopierat från original", + "Copyright © 2014-2016 the following Contributors:": "Copyright © 2014-2016 följande bidragare:", "Copyright © 2015 the following Contributors:": "Copyright © 2015 följande medverkande:", "Danger!": "Fara!", "Delete": "Ta bort", "Deleted": "Borttaget", "Device \"{%name%}\" ({%device%} at {%address%}) wants to connect. Add new device?": "Enhet \"{{name}}\" ({{device}} på {{address}}) vill ansluta. Lägg till ny enhet?", - "Device ID": "Enhets-ID", + "Device ID": "Enhets ID", "Device Identification": "Enhetsidentifikation", "Device Name": "Enhetsnamn", "Device {%device%} ({%address%}) wants to connect. Add new device?": "Enheten {{device}} ({{address}}) vill ansluta. Lägg till ny enhet?", "Devices": "Enheter", - "Disconnected": "Ej ansluten", - "Discovery": "Uppslagning", + "Disconnected": "Frånkopplad", + "Discovery": "Upptäckt", "Documentation": "Dokumentation", - "Download Rate": "Nedladdningshastighet", - "Downloaded": "Nerladdat", - "Downloading": "Laddar ner", + "Download Rate": "Hämtningshastighet", + "Downloaded": "Hämtat", + "Downloading": "Hämtar", "Edit": "Redigera", "Edit Device": "Redigera enhet", "Edit Folder": "Redigera katalog", "Editing": "Redigerar", "Enable NAT traversal": "Aktivera NAT traversering", "Enable Relaying": "Aktivera reläa", - "Enable UPnP": "Använd UPnP", + "Enable UPnP": "Aktivera UPnP", "Enter comma separated (\"tcp://ip:port\", \"tcp://host:port\") addresses or \"dynamic\" to perform automatic discovery of the address.": "Ange kommaseparerade (\"tcp://ip:port\", \"tcp://host:port\")-adresser eller ordet \"dynamic\" för att använda automatisk uppslagning.", "Enter ignore patterns, one per line.": "Ange filmönster, ett per rad.", "Error": "Fel", "External File Versioning": "Extern versionshantering", - "Failed Items": "Misslyckade filer", + "Failed Items": "Misslyckade objekt", "File Pull Order": "Hämtningsprioritering av filer", "File Versioning": "Versionshantering", "File permission bits are ignored when looking for changes. Use on FAT file systems.": "Filrättigheter ignoreras vid sökning efter förändringar. Används på FAT-filsystem.", @@ -71,17 +71,17 @@ "Files are moved to date stamped versions in a .stversions folder when replaced or deleted by Syncthing.": "Filer flyttas till datummärkta versioner i en .stversions-mapp när de ersatts eller raderats av Syncthing.", "Files are protected from changes made on other devices, but changes made on this device will be sent to the rest of the cluster.": "Filer skyddas från ändringar gjorda på andra enheter, men ändringar som görs på den här noden skickas till de andra klustermedlemmarna.", "Folder": "Katalog", - "Folder ID": "Katalog-ID", - "Folder Label": "Katalog etikett", - "Folder Master": "Huvudlagring", - "Folder Path": "Sökväg", + "Folder ID": "Katalog ID", + "Folder Label": "Katalogens etikett", + "Folder Master": "Huvudkatalog", + "Folder Path": "Katalogens sökväg", "Folder Type": "Katalogtyp", "Folders": "Kataloger", - "GUI": "GUI", - "GUI Authentication Password": "GUI-lösenord", - "GUI Authentication User": "GUI-användare", - "GUI Listen Addresses": "GUI-adress", - "Generate": "Skapa", + "GUI": "Grafiskt gränssnitt", + "GUI Authentication Password": "Grafiska gränssnittets lösenord", + "GUI Authentication User": "Grafiska gränssnittets användare", + "GUI Listen Addresses": "Grafiska gränssnittets avlyssningsadresser", + "Generate": "Generera", "Global Discovery": "Global uppslagning", "Global Discovery Server": "Global uppslagningsserver", "Global Discovery Servers": "Globala uppslagningsservrar", @@ -96,18 +96,18 @@ "Introducer": "introduktör", "Inversion of the given condition (i.e. do not exclude)": "Vänder på villkoret, d.v.s. exkluderar inte.", "Keep Versions": "Behåll versioner", - "Largest First": "Störst först", - "Last File Received": "Senast Mottagna Fil", - "Last Scan": "Senast skanning", - "Last seen": "Senast online", + "Largest First": "Största först", + "Last File Received": "Senaste fil mottagen", + "Last Scan": "Senaste skanning", + "Last seen": "Senast sedd", "Later": "Senare", "Listeners": "Lyssnare", "Local Discovery": "Lokal uppslagning", "Local State": "Lokal status", - "Local State (Total)": "Lokal status (Total)", + "Local State (Total)": "Lokal status (totalt)", "Major Upgrade": "Stor uppgradering", "Master": "Huvud", - "Maximum Age": "Högsta ålder", + "Maximum Age": "Maximum ålder", "Metadata Only": "Endast metadata", "Minimum Free Disk Space": "Minimum ledigt diskutrymme", "Move to top of queue": "Flytta till överst i kön", @@ -126,39 +126,39 @@ "Optional descriptive label for the folder. Can be different on each device.": "Valfri beskrivande etikett för katalogen. Kan vara olika på varje enhet.", "Options": "Alternativ", "Out of Sync": "Osynkroniserad", - "Out of Sync Items": "Osynkroniserade poster", + "Out of Sync Items": "Osynkroniserade objekt", "Outgoing Rate Limit (KiB/s)": "Max uppladdningshastighet (KiB/s)", - "Override Changes": "Skriv över ändringar", + "Override Changes": "Åsidosätt förändringar", "Path to the folder on the local computer. Will be created if it does not exist. The tilde character (~) can be used as a shortcut for": "Sökväg till katalogen på din dator. Kommer att skapas om det inte finns. Tecknet tilde (~) kan användas som en genväg för", "Path where versions should be stored (leave empty for the default .stversions folder in the folder).": "Sökväg där versioner sparas (lämna tomt för att använda .stversions i den ordinarie katalogen).", "Pause": "Paus", "Paused": "Pausad", "Please consult the release notes before performing a major upgrade.": "Läs igenom versionsnyheterna innan den stora uppgraderingen.", - "Please set a GUI Authentication User and Password in the Settings dialog.": "Ställ in ett grafiskt användarautentisering och lösenord i dialogrutan Inställningar.", + "Please set a GUI Authentication User and Password in the Settings dialog.": "Ställ in ett grafiska gränssnittets användarautentisering och lösenord i inställningsdialogrutan.", "Please wait": "Var god vänta", "Preview": "Förhandsgranska", "Preview Usage Report": "Förhandsgranska statistik", - "Quick guide to supported patterns": "Snabb guide till filmönster som stöds", - "RAM Utilization": "Minnesanvändning", + "Quick guide to supported patterns": "Snabb handledning till mönster som stöds", + "RAM Utilization": "RAM användning", "Random": "Slumpmässig", "Relay Servers": "Reläservrar", "Relayed via": "Vidarbefordras via", - "Relays": "Vidarbefordringar", + "Relays": "Reläservrar", "Release Notes": "Versionsanteckningar", "Remote Devices": "Fjärrenheter", "Remove": "Ta bort", "Required identifier for the folder. Must be the same on all cluster devices.": "Krävs identifierare för katalogen. Måste vara densamma på alla kluster enheter.", - "Rescan": "Uppdatera", - "Rescan All": "Uppdatera alla", - "Rescan Interval": "Uppdateringsintervall", + "Rescan": "Skanna om", + "Rescan All": "Skanna om alla", + "Rescan Interval": "Omskanningsintervall", "Restart": "Starta om", "Restart Needed": "Omstart behövs", "Restarting": "Startar om", "Resume": "Återuppta", "Reused": "Återanvänt", "Save": "Spara", - "Scan Time Remaining": "Granska återstående tid", - "Scanning": "Uppdaterar", + "Scan Time Remaining": "Återstående skanningstid", + "Scanning": "Skannar", "Select the devices to share this folder with.": "Ange enheterna att dela den här katalogen med.", "Select the folders to share with this device.": "Välj kataloger att dela med den här enheten.", "Settings": "Inställningar", @@ -166,13 +166,13 @@ "Share Folder": "Dela katalog", "Share Folders With Device": "Dela kataloger med enhet", "Share With Devices": "Dela med enheter", - "Share this folder?": "Dela den här katalogen?", + "Share this folder?": "Dela denna katalog?", "Shared With": "Delad med", "Short identifier for the folder. Must be the same on all cluster devices.": "Kort identifieringssträng för katalogen. Måste vara samma på alla enheter i klustret.", "Show ID": "Visa ID", "Show QR": "Visa QR", - "Shown instead of Device ID in the cluster status. Will be advertised to other devices as an optional default name.": "Visas i stället för enhets-ID. Skickas till andra enheter som namn på denna enhet.", - "Shown instead of Device ID in the cluster status. Will be updated to the name the device advertises if left empty.": "Visas i stället för enhets-ID. Sätts till namnet på den andra enheten vid första anslutning om det lämnas tomt.", + "Shown instead of Device ID in the cluster status. Will be advertised to other devices as an optional default name.": "Visas i stället för enhetens ID. Skickas till andra enheter som namn på denna enhet.", + "Shown instead of Device ID in the cluster status. Will be updated to the name the device advertises if left empty.": "Visas i stället för enhetens ID. Sätts till namnet på den andra enheten vid första anslutning om det lämnas tomt.", "Shutdown": "Stäng av", "Shutdown Complete": "Avstängning klar", "Simple File Versioning": "Enkel versionshantering", @@ -180,7 +180,7 @@ "Smallest First": "Minst först", "Source Code": "Källkod", "Staggered File Versioning": "Versionshantering i intervall", - "Start Browser": "Starta browser", + "Start Browser": "Starta webbläsare", "Statistics": "Statistik", "Stopped": "Stoppad", "Support": "Support", @@ -191,23 +191,23 @@ "Syncthing is restarting.": "Syncthing startar om.", "Syncthing is upgrading.": "Syncthing uppgraderas.", "Syncthing seems to be down, or there is a problem with your Internet connection. Retrying…": "Syncthing verkar avstängd, eller finns det problem med din Internetanslutning. Försöker igen...", - "Syncthing seems to be experiencing a problem processing your request. Please refresh the page or restart Syncthing if the problem persists.": "Syncthing verkar ha drabbats av ett problem. Uppdatera sidan eller starta om Syncthing om problemet kvarstår.", + "Syncthing seems to be experiencing a problem processing your request. Please refresh the page or restart Syncthing if the problem persists.": "Syncthing verkar ha drabbats av ett problem med behandlingen av din begäran. Uppdatera sidan eller starta om Syncthing om problemet kvarstår.", "The Syncthing admin interface is configured to allow remote access without a password.": "Syncthing administratör gränssnittet är konfigurerat för att tillåta fjärrtillträde utan ett lösenord.", "The aggregated statistics are publicly available at the URL below.": "Den aggregerade statistiken är offentligt tillgängliga på webbadressen nedan.", "The aggregated statistics are publicly available at {%url%}.": "Sammanställd statistik finns publikt tillgänglig på {{url}}.", "The configuration has been saved but not activated. Syncthing must restart to activate the new configuration.": "Konfigurationen har sparats men inte aktiverats. Syncthing måste startas om för att aktivera den nya konfigurationen.", - "The device ID cannot be blank.": "Enhets-ID kan inte vara tomt.", - "The device ID to enter here can be found in the \"Actions > Show ID\" dialog on the other device. Spaces and dashes are optional (ignored).": "Enhets-ID som behövs här kan du hitta i \"Redigera > Visa ID\"-dialogen på den andra enheten. Mellanrum och bindestreck är valfria (ignoreras).", - "The device ID to enter here can be found in the \"Edit > Show ID\" dialog on the other device. Spaces and dashes are optional (ignored).": "Enhets-ID som behövs här kan du hitta i \"Redigera > Visa ID\"-dialogen på den andra enheten. Mellanrum och bindestreck är valfria (ignoreras).", + "The device ID cannot be blank.": "Enhetens ID kan inte vara tomt.", + "The device ID to enter here can be found in the \"Actions > Show ID\" dialog on the other device. Spaces and dashes are optional (ignored).": "Enhetens ID som behövs här kan du hitta i \"Redigera > Visa ID\"-dialogen på den andra enheten. Mellanrum och bindestreck är valfria (ignoreras).", + "The device ID to enter here can be found in the \"Edit > Show ID\" dialog on the other device. Spaces and dashes are optional (ignored).": "Enhetens ID som behövs här kan du hitta i \"Redigera > Visa ID\"-dialogen på den andra enheten. Mellanrum och bindestreck är valfria (ignoreras).", "The encrypted usage report is sent daily. It is used to track common platforms, folder sizes and app versions. If the reported data set is changed you will be prompted with this dialog again.": "Den krypterade användarstatistiken skickas dagligen. Den används för att spåra vanliga plattformar, katalogstorlekar och versioner. Om datan som rapporteras ändras så kommer du att bli tillfrågad igen.", - "The entered device ID does not look valid. It should be a 52 or 56 character string consisting of letters and numbers, with spaces and dashes being optional.": "Det inmatade enhets-ID:t verkar inte korrekt. Det ska vara en 52 eller 56 teckens sträng bestående av siffror och bokstäver, eventuellt med mellanrum och bindestreck.", + "The entered device ID does not look valid. It should be a 52 or 56 character string consisting of letters and numbers, with spaces and dashes being optional.": "Det inmatade enhetens ID verkar inte korrekt. Det ska vara en 52 eller 56 teckens sträng bestående av siffror och bokstäver, eventuellt med mellanrum och bindestreck.", "The first command line parameter is the folder path and the second parameter is the relative path in the folder.": "Den första kommandoparametern är sökvägen till mappen och den andra parametern är den relativa sökvägen i mappen.", - "The folder ID cannot be blank.": "Ange ett enhets-ID.", - "The folder ID must be a short identifier (64 characters or less) consisting of letters, numbers and the dot (.), dash (-) and underscode (_) characters only.": "Katalog-ID:t måste vara en kort sträng (64 tecken eller mindre), bestående av endast bokstäver, siffror, punkt (.), bindestreck (-) och understreck (_).", - "The folder ID must be unique.": "Katalog-ID:t måste vara unikt.", - "The folder path cannot be blank.": "Ange en sökväg.", + "The folder ID cannot be blank.": "Katalogens ID får inte vara tomt.", + "The folder ID must be a short identifier (64 characters or less) consisting of letters, numbers and the dot (.), dash (-) and underscode (_) characters only.": "Katalogens ID måste vara en kort sträng (64 tecken eller mindre), bestående av endast bokstäver, siffror, punkt (.), bindestreck (-) och understreck (_).", + "The folder ID must be unique.": "Katalogens ID måste vara unikt.", + "The folder path cannot be blank.": "Katalogsökvägen får inte vara tom.", "The following intervals are used: for the first hour a version is kept every 30 seconds, for the first day a version is kept every hour, for the first 30 days a version is kept every day, until the maximum age a version is kept every week.": "De följande intervallen används: varje 30 sekunder under den första timmen; varje timme under den första dagen; varje dag för de första 30 dagarna; varje vecka tills den maximala åldersgränsen uppnås.", - "The following items could not be synchronized.": "Följande filer kunde inte synkroniseras.", + "The following items could not be synchronized.": "Följande objekt kunde inte synkroniseras.", "The maximum age must be a number and cannot be blank.": "Åldersgränsen måste vara ett tal och kan inte lämnas tomt.", "The maximum time to keep a version (in days, set to 0 to keep versions forever).": "Den längsta tiden att behålla en version (i dagar, sätt till 0 för att behålla versioner för evigt).", "The minimum free disk space percentage must be a non-negative number between 0 and 100 (inclusive).": "Minimum ledigt diskutrymme i procent måste vara en icke negativ siffra mellan 0 och 100 (inklusive).", @@ -215,36 +215,36 @@ "The number of days to keep files in the trash can. Zero means forever.": "Antal dagar som filer ligger kvar i papperskorgen. Noll betyder för alltid.", "The number of old versions to keep, per file.": "Antalet gamla versioner som ska behållas, per fil.", "The number of versions must be a number and cannot be blank.": "Antalet versioner måste vara ett nummer och kan inte lämnas tomt.", - "The path cannot be blank.": "Ange en sökväg", + "The path cannot be blank.": "Sökvägen kan inte vara tom.", "The rate limit must be a non-negative number (0: no limit)": "Frekvensgränsen måste vara ett icke-negativt tal (0: ingen gräns)", "The rescan interval must be a non-negative number of seconds.": "Förnyelseintervallet måste vara ett positivt antal sekunder", "They are retried automatically and will be synced when the error is resolved.": "De omprövas automatiskt och kommer att synkroniseras när felet är löst.", "This Device": "Denna enhet", "This can easily give hackers access to read and change any files on your computer.": "Detta kan lätt ge hackare tillgång till att läsa och ändra några filer på datorn.", "This is a major version upgrade.": "Det här är en stor uppgradering.", - "Trash Can File Versioning": "Versionshantering på filer i papperskorgen", - "Unknown": "Okänt", + "Trash Can File Versioning": "Versionshantering av filer i papperskorgen", + "Unknown": "Okänd", "Unshared": "Inte delad", "Unused": "Oanvänd", - "Up to Date": "Helt uppdaterad", + "Up to Date": "Uppdaterad", "Updated": "Uppdaterad", "Upgrade": "Uppgradering", "Upgrade To {%version%}": "Uppgradera till {{version}}", "Upgrading": "Uppgraderar", "Upload Rate": "Uppladdningshastighet", "Uptime": "Tid sedan start", - "Use HTTPS for GUI": "Använd HTTPS för GUI", + "Use HTTPS for GUI": "Använd HTTPS för grafiska gränssnittet", "Version": "Version", - "Versions Path": "Katalog för versioner", + "Versions Path": "Sökväg för versioner", "Versions are automatically deleted if they are older than the maximum age or exceed the number of files allowed in an interval.": "Versioner tas bort automatiskt när de är äldre än den maximala åldersgränsen eller överstiger frekvensen i sitt interval.", "Warning, this path is a subdirectory of an existing folder \"{%otherFolder%}\".": "Varning, denna sökväg är en underkatalog till en befintlig katalog \"{{otherFolder}}\".", "When adding a new device, keep in mind that this device must be added on the other side too.": "När du lägger till en ny enhet, kom ihåg att den här enheten måste läggas till på den andra enheten också.", - "When adding a new folder, keep in mind that the Folder ID is used to tie folders together between devices. They are case sensitive and must match exactly between all devices.": "När du lägger till ny katalog, tänk på att katalog-ID:t knyter ihop katalogen mellan olika noder. De måste vara exakt desamma mellan noder och stora eller små bokstäver har betydelse.", + "When adding a new folder, keep in mind that the Folder ID is used to tie folders together between devices. They are case sensitive and must match exactly between all devices.": "När du lägger till ny katalog, tänk på att katalogens ID knyter ihop katalogen mellan olika noder. De måste vara exakt desamma mellan noder och stora eller små bokstäver har betydelse.", "Yes": "Ja", "You must keep at least one version.": "Du måste behålla åtminstone en version.", "days": "dagar", "full documentation": "fullständig dokumentation", - "items": "poster", + "items": "objekt", "{%device%} wants to share folder \"{%folder%}\".": "{{device}} vill dela katalogen \"{{folder}}\".", "{%device%} wants to share folder \"{%folderLabel%}\" ({%folder%}).": "{{device}} vill dela katalogen \"{{folderLabel}}\" ({{folder}}).", "{%device%} wants to share folder \"{%folderlabel%}\" ({%folder%}).": "{{device}} vill dela katalogen \"{{folderlabel}}\" ({{folder}})." diff --git a/man/syncthing-bep.7 b/man/syncthing-bep.7 index 030d267b..8a5349d8 100644 --- a/man/syncthing-bep.7 +++ b/man/syncthing-bep.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-BEP" "7" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-BEP" "7" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing-bep \- Block Exchange Protocol v1 . @@ -61,7 +61,7 @@ level protocols providing encryption and authentication. |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| | Encryption & Auth (TLS 1.2) | |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| -| TCP | +| Reliable Transport | |\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-| v ... v .ft P @@ -91,385 +91,263 @@ the sender need not await a response to one message before sending another. .sp The underlying transport protocol MUST guarantee reliable packet delivery. +.sp +In this document, in diagrams and text, "bit 0" refers to the \fImost +significant\fP bit of a word; "bit 15" is thus the least significant bit of a +16 bit word (int16) and "bit 31" is the least significant bit of a 32 bit +word (int32). Non protocol buffer integers are always represented in network +byte order (i.e., big endian) and are signed unless stated otherwise, but +when describing message lengths negative values do not make sense and the +most significant bit MUST be zero. +.sp +The protocol buffer schemas in this document are in \fBproto3\fP syntax. This +means, among other things, that all fields are optional and will assume +their default value when missing. This does not nececessarily mean that a +message is \fIvalid\fP with all fields empty \- for example, an index entry for a +file that does not have a name is not useful and MAY be rejected by the +implementation. However the folder label is for human consumption only so an +empty label should be accepted \- the implementation will have to choose some +way to represent the folder, perhaps by using the ID in it\(aqs place or +automatically generating a label. .SH PRE-AUTHENTICATION MESSAGES .sp AFTER establishing a connection, but BEFORE performing any authentication, -\fIdevices\fP MUST exchange Hello messages. +devices MUST exchange Hello messages. .sp -Hello messages are used to carry additional information about the peer, which -might be of interest to the user even if the peer is not permitted to -communicate due to failing authentication. +Hello messages are used to carry additional information about the peer, +which might be of interest to the user even if the peer is not permitted to +communicate due to failing authentication. Note that the certificate based +authentication may be considered part of the TLS handshake that precedes the +Hello message exchange, but even in the case that a connection is rejected a +Hello message must be sent before the connection is terminated. .sp -Hello messages MUST be prefixed with a magic number \fB0x9F79BC40\fP -represented in network byte order (BE), followed by 4 bytes representing the -size of the message in network byte order (BE), followed by the content of -the Hello message itself. The size of the contents of Hello message MUST be -less or equal to 1024 bytes. +Hello messages MUST be prefixed with an int32 containing the magic number +\fB0x2EA7D90B\fP, followed by an int16 representing the size of the message, +followed by the contents of the Hello message itself. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -Prefix Structure: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Magic | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Content of HelloMessage \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ - -HelloMessage Structure: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Device Name (length + padded data) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Client Name (length + padded data) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Client Version (length + padded data) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ + 0 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Magic | +| (32 bits) | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Length | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +/ / +\e Hello \e +/ / ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ .ft P .fi .UNINDENT .UNINDENT -.SS Fields (HelloMessage) .sp -The \fBDevice Name\fP is a human readable (configured or auto detected) device +The Hello message itself is in protocol buffer format with the following schema: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +message Hello { + string device_name = 1; + string client_name = 2; + string client_version = 3; +} +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Fields (Hello message) +.sp +The \fBdevice_name\fP is a human readable (configured or auto detected) device name or host name, for the remote device. .sp -The \fBClient Name\fP and \fBClient Version\fP identifies the implementation. The +The \fBclient_name\fP and \fBclient_version\fP identifies the implementation. The values SHOULD be simple strings identifying the implementation name, as a user would expect to see it, and the version string in the same manner. An -example Client Name is "syncthing" and an example Client Version is "v0.7.2". -The Client Version field SHOULD follow the patterns laid out in the \fI\%Semantic +example client name is "syncthing" and an example client version is "v0.7.2". +The client version field SHOULD follow the patterns laid out in the \fI\%Semantic Versioning\fP <\fBhttp://semver.org/\fP> standard. -.SS XDR -.INDENT 0.0 -.INDENT 3.5 .sp -.nf -.ft C -struct HelloMessage { - string DeviceName<64>; - string ClientName<64>; - string ClientVersion<64>; -}; -.ft P -.fi -.UNINDENT -.UNINDENT -.sp -Immediately after exchanging Hello messages, the connection should be -dropped if device does not pass authentication. +Immediately after exchanging Hello messages, the connection MUST be dropped +if the remote device does not pass authentication. .SH POST-AUTHENTICATION MESSAGES .sp -Every message starts with one 32 bit word indicating the message version, type -and ID, followed by the length of the message. The header is in network byte -order, i.e. big endian. In this document, in diagrams and text, "bit 0" refers -to the \fImost significant\fP bit of a word; "bit 31" is thus the least -significant bit of a 32 bit word. +Every message post authentication is made up of several parts: +.INDENT 0.0 +.IP \(bu 2 +A header length word +.IP \(bu 2 +A \fBHeader\fP +.IP \(bu 2 +A message length word +.IP \(bu 2 +A \fBMessage\fP +.UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Ver | Message ID | Type | Reserved |C| -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ + 0 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Header Length | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +/ / +\e Header \e +/ / ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +| Message Length | +| (32 bits) | ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +/ / +\e Message \e +/ / ++\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ .ft P .fi .UNINDENT .UNINDENT .sp -For BEP v1 the \fBVersion\fP field is set to zero. Future versions with -incompatible message formats will increment the Version field. A message -with an unknown version is a protocol error and MUST result in the -connection being terminated. A client supporting multiple versions MAY -retry with a different protocol version upon disconnection. +The header length word is 16 bits. It indicates the length of the following +\fBHeader\fP message. The Header is in protocol buffer format. The Header +describes the type and compression status of the following message. .sp -The \fBMessage ID\fP is set to a unique value for each transmitted Request -message. In Response messages it is set to the Message ID of the corresponding -Request message. The uniqueness requirement implies that no more than 4096 -request messages may be outstanding at any given moment. For message types -that do not have a corresponding response (Cluster Configuration, Index, etc.) -the Message ID field is irrelevant and SHOULD be set to zero. +The message is preceded by the 32 bit message length word and is one of the +concrete BEP messages described below, identified by the \fBtype\fP field of +the Header. .sp -The \fBType\fP field indicates the type of data following the message header -and is one of the integers defined below. A message of an unknown type -is a protocol error and MUST result in the connection being terminated. -.sp -The \fBCompression\fP bit "C" indicates the compression used for the message. -.sp -For C=0: +As always, the length words are in network byte order (big endian). .INDENT 0.0 -.IP \(bu 2 -The Length field contains the length, in bytes, of the uncompressed -message data. -.IP \(bu 2 -The message is not compressed. +.INDENT 3.5 +.sp +.nf +.ft C +message Header { + MessageType type = 1; + MessageCompression compression = 2; +} + +enum MessageType { + CLUSTER_CONFIG = 0; + INDEX = 1; + INDEX_UPDATE = 2; + REQUEST = 3; + RESPONSE = 4; + DOWNLOAD_PROGRESS = 5; + PING = 6; + CLOSE = 7; +} + +enum MessageCompression { + NONE = 0; + LZ4 = 1; +} +.ft P +.fi +.UNINDENT .UNINDENT .sp -For C=1: -.INDENT 0.0 -.IP \(bu 2 -The Length field contains the length, in bytes, of the compressed -message data plus a four byte uncompressed length field. -.IP \(bu 2 -The compressed message data is preceded by a 32 bit field denoting -the length of the uncompressed message. -.IP \(bu 2 -The message data is compressed using the LZ4 format and algorithm -described in \fI\%http://www.lz4.org/\fP\&. -.UNINDENT +When the \fBcompression\fP field is \fBNONE\fP, the message is directly in +protocol buffer format. .sp -All data within the message (post decompression, if compression is in -use) MUST be in XDR (RFC 1014) encoding. All fields shorter than 32 bits -and all variable length data MUST be padded to a multiple of 32 bits. -The actual data types in use by BEP, in XDR naming convention, are the -following: -.INDENT 0.0 -.TP -.B (unsigned) int: -(unsigned) 32 bit integer -.TP -.B (unsigned) hyper: -(unsigned) 64 bit integer -.TP -.B opaque<> -variable length opaque data -.TP -.B string<> -variable length string -.UNINDENT -.sp -The transmitted length of string and opaque data is the length of actual -data, excluding any added padding. The encoding of opaque<> and string<> -are identical, the distinction being solely one of interpretation. -Opaque data should not be interpreted but can be compared bytewise to -other opaque data. All strings MUST use the Unicode UTF\-8 encoding, -normalization form C. -.SS Cluster Config (Type = 0) +When the compression field is \fBLZ4\fP, the message consists of a 32 bit +integer describing the uncompressed message length followed by a single LZ4 +block. After decompressing the LZ4 block it should be interpreted as a +protocol buffer message just as in the uncompressed case. +.SH MESSAGE SUBTYPES +.SS Cluster Config .sp This informational message provides information about the cluster configuration as it pertains to the current connection. A Cluster Config -message MUST be the first message sent on a BEP connection. Additional -Cluster Config messages MUST NOT be sent after the initial exchange. -.SS Graphical Representation +message MUST be the first post authentication message sent on a BEP +connection. Additional Cluster Config messages MUST NOT be sent after the +initial exchange. +.SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -ClusterConfigMessage Structure: +message ClusterConfig { + repeated Folder folders = 1; +} - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Folders | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more Folder Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Options | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more Option Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +message Folder { + string id = 1; + string label = 2; + bool read_only = 3; + bool ignore_permissions = 4; + bool ignore_delete = 5; + bool disable_temp_indexes = 6; -Folder Structure: + repeated Device devices = 16; +} - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of ID | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e ID (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Label (length + padded data) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Devices | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more Device Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Flags | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Options | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more Option Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +message Device { + bytes id = 1; + string name = 2; + repeated string addresses = 3; + Compression compression = 4; + string cert_name = 5; + int64 max_local_version = 6; + bool introducer = 7; +} -Device Structure: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of ID | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e ID (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Name | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Name (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Addresses | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Address | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Address (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Compression | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Cert Name | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Cert Name (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| | -+ Max Local Version (64 bits) + -| | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Flags | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Options | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more Option Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ - -Option Structure: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Key | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Key (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Value | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Value (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +enum Compression { + METADATA = 0; + NEVER = 1; + ALWAYS = 2; +} .ft P .fi .UNINDENT .UNINDENT -.SS Fields (ClusterConfigMessage) +.SS Fields (Cluster Config Message) .sp -The \fBFolders\fP field contains the list of folders that will be synchronized +The \fBfolders\fP field contains the list of folders that will be synchronized over the current connection. +.SS Fields (Folder Message) .sp -The \fBOptions\fP field is a list of options that apply to the current -connection. The options are used in an implementation specific manner. The -options list is conceptually a map of keys to values, although it is -transmitted in the form of a list of key and value pairs, both of string type. -Key ID:s are implementation specific. An implementation MUST ignore unknown -keys. An implementation MAY impose limits on the length keys and values. The -options list may be used to inform devices of relevant local configuration -options such as rate limiting or make recommendations about request -parallelism, device priorities, etc. An empty options list is valid for -devices not having any such information to share. Devices MAY NOT make any -assumptions about peers acting in a specific manner as a result of sent -options. -.SS Fields (Folder Structure) +The \fBid\fP field contains the folder ID, which is the unique identifier of +the folder. .sp -The \fBID\fP field contains the folder ID, as a human readable string. +The \fBlabel\fP field contains the folder label, the human readable name of +the folder. .sp -The \fBLabel\fP field contains the folder label, as human readable name for the folder. +The \fBread only\fP field is set for folders that the device will accept no +updates from the network for. .sp -The \fBDevices\fP field is list of devices participating in sharing this folder. +The \fBignore permissions\fP field is set for folders that the device will not +accept or announce file permissions for. .sp -The \fBFlags\fP field contains flags that affect the behavior of the folder. The -folder Flags field contains the following single bit flags: -.INDENT 0.0 -.INDENT 3.5 +The \fBignore delete\fP field is set for folders that the device will ignore +deletes for. .sp -.nf -.ft C - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Reserved |T|D|P|R| -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B Bit 31 ("R", Read Only) -is set for folders that the device will accept no updates from the network -for. -.TP -.B Bit 30 ("P", Ignore Permissions) -is set for folders that the device will not accept or announce file -permissions for. -.TP -.B Bit 29 ("D", Ignore Deletes) -is set for folders that the device will ignore deletes for. -.TP -.B Bit 28 ("T", Disable Temporary Indexes) -is set for folders that will not dispatch and do not wish to receive -progress updates about partially downloaded files via DownloadProgress -.INDENT 7.0 -.INDENT 3.5 -messages. -.UNINDENT -.UNINDENT -.UNINDENT +The \fBdisable temp indexes\fP field is set for folders that will not dispatch +and do not wish to receive progress updates about partially downloaded files +via Download Progress messages. .sp -The \fBOptions\fP field contains a list of options that apply to the folder. -.SS Fields (Device Structure) +The \fBdevices\fP field is a list of devices participating in sharing this +folder. +.SS Fields (Device Message) .sp -The device \fBID\fP field is a 32 byte number that uniquely identifies the +The device \fBid\fP field is a 32 byte number that uniquely identifies the device. For instance, the reference implementation uses the SHA\-256 of the device X.509 certificate. .sp -The \fBName\fP field is a human readable name assigned to the described device +The \fBname\fP field is a human readable name assigned to the described device by the sending device. It MAY be empty and it need not be unique. .sp -The list of \fBAddressess\fP is that used by the sending device to connect to +The list of \fBaddresses\fP is that used by the sending device to connect to the described device. .sp -The \fBCompression\fP field indicates the compression mode in use for this +The \fBcompression\fP field indicates the compression mode in use for this device and folder. The following values are valid: .INDENT 0.0 .TP @@ -483,10 +361,10 @@ Compression disabled. No compression is used on any message. Compress always. Metadata messages as well as Response messages are compressed. .UNINDENT .sp -The \fBCert Name\fP field indicates the expected certificate name for this +The \fBcert name\fP field indicates the expected certificate name for this device. It is commonly blank, indicating to use the implementation default. .sp -The \fBMax Local Version\fP field contains the highest local file +The \fBmax local version\fP field contains the highest local file version number of the files already known to be in the index sent by this device. If nothing is known about the index of a given device, this field MUST be set to zero. When receiving a Cluster Config message with @@ -494,107 +372,9 @@ a non\-zero Max Local Version for the local device ID, a device MAY elect to send an Index Update message containing only files with higher local version numbers in place of the initial Index message. .sp -The \fBFlags\fP field indicates the sharing mode of the folder and other device -& folder specific settings. See the discussion on Sharing Modes. The Device -Flags field contains the following single bit flags: -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Reserved |Pri| Reserved |I|R|T| -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B Bit 31 ("T", Trusted) -is set for devices that participate in trusted -mode. -.TP -.B Bit 30 ("R", Read Only) -is set for devices that participate in read -only mode. -.TP -.B Bit 29 ("I", Introducer) -is set for devices that are trusted as -cluster introducers. -.TP -.B Bits 16 through 28 -are reserved and MUST be set to zero. -.TP -.B Bits 14\-15 ("Pri", Priority) -indicate the device\(aqs upload priority for this -folder. Possible values are: -.INDENT 7.0 -.TP -.B 00 -The default. Normal priority. -.TP -.B 01 -High priority. Other devices SHOULD favour requesting files -from this device over devices with normal or low priority. -.TP -.B 10 -Low priority. Other devices SHOULD avoid requesting files from -this device when they are available from other devices. -.TP -.B 11 -Sharing disabled. Other devices SHOULD NOT request files from -this device. -.UNINDENT -.TP -.B Bits 0 through 14 -are reserved and MUST be set to zero. -.UNINDENT -.sp -Exactly one of the T and R bits MUST be set. -.sp -The \fBOptions\fP field contains a list of options that apply to the device. -.SS XDR -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -struct ClusterConfigMessage { - Folder Folders<1000000>; - Option Options<64>; -}; - -struct Folder { - string ID<256>; - string Label<256>; - Device Devices<1000000>; - unsigned int Flags; - Option Options<64>; -}; - -struct Device { - opaque ID<32>; - string Name<64>; - string Addresses<64>; - unsigned int Compression; - string CertName<64>; - hyper MaxLocalVersion; - unsigned int Flags; - Option Options<64>; -}; - -struct Option { - string Key<64>; - string Value<1024>; -}; -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Index (Type = 1) and Index Update (Type = 6) +The \fBintroducer\fP field is set for devices that are trusted as cluster +introducers. +.SS Index and Index Update .sp The Index and Index Update messages define the contents of the senders folder. An Index message represents the full contents of the folder and @@ -603,404 +383,209 @@ index with new information, not affecting any entries not included in the message. An Index Update MAY NOT be sent unless preceded by an Index, unless a non\-zero Max Local Version has been announced for the given folder by the peer device. -.SS Graphical Representation +.sp +The Index and Index Update messages are currently identical in format, +although this is not guaranteed to be the case in the future. +.SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -IndexMessage Structure: +message Index { + string folder = 1; + repeated FileInfo files = 2; +} - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Folder | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Folder (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Files | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more FileInfo Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Flags | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Options | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more Option Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +message IndexUpdate { + string folder = 1; + repeated FileInfo files = 2; +} -FileInfo Structure: +message FileInfo { + string name = 1; + FileInfoType type = 2; + int64 size = 3; + uint32 permissions = 4; + int64 modified = 5; + bool deleted = 6; + bool invalid = 7; + bool no_permissions = 8; + Vector version = 9; + int64 local_version = 10; - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Name | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Name (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Flags | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| | -+ Modified (64 bits) + -| | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Version (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| | -+ Local Version (64 bits) + -| | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Blocks | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more BlockInfo Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ + repeated BlockInfo Blocks = 16; +} -Vector Structure: +enum FileInfoType { + FILE = 0; + DIRECTORY = 1; + SYMLINK_FILE = 2; + SYMLINK_DIRECTORY = 3; + SYMLINK_UNKNOWN = 4; +} - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Counters | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more Counter Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +message BlockInfo { + int64 offset = 1; + int32 size = 2; + bytes hash = 3; +} -Counter Structure: +message Vector { + repeated Counter counters = 1; +} - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| | -+ ID (64 bits) + -| | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| | -+ Value (64 bits) + -| | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ - - -BlockInfo Structure: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Size | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Hash | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Hash (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +message Counter { + uint64 id = 1; + uint64 value = 2; +} .ft P .fi .UNINDENT .UNINDENT .SS Fields (Index Message) .sp -The \fBFolder\fP field identifies the folder that the index message pertains to. +The \fBfolder\fP field identifies the folder that the index message pertains to. .sp -\fBFiles\fP +The \fBfiles\fP field is a list of files making up the index information. +.SS Fields (FileInfo Message) .sp -The \fBFlags\fP field is reserved for future use and MUST currently be set to -zero. -.sp -The \fBOptions\fP list is implementation defined and as described in the -ClusterConfig message section. -.SS Fields (FileInfo Structure) -.sp -The \fBName\fP is the file name path relative to the folder root. Like all +The \fBname\fP is the file name path relative to the folder root. Like all strings in BEP, the Name is always in UTF\-8 NFC regardless of operating -system or file system specific conventions. The Name field uses the -slash character ("/") as path separator, regardless of the -implementation\(aqs operating system conventions. The combination of Folder -and Name uniquely identifies each file in a cluster. +system or file system specific conventions. The name field uses the slash +character ("/") as path separator, regardless of the implementation\(aqs +operating system conventions. The combination of folder and name uniquely +identifies each file in a cluster. .sp -The \fBFlags\fP field is made up of the following single bit flags: -.INDENT 0.0 -.INDENT 3.5 +The \fBtype\fP field contains the type of the described item. The type is one +of \fBfile (0)\fP, \fBdirectory (1)\fP, \fBsymlink to file (2)\fP, \fBsymlink to +directory (3)\fP, or \fBsymlink to unknown target (4)\fP\&. The distinction +between the various types of symlinks is not required on all operating +systems \- the implementation SHOULD nonetheless indicate the target type +when possible. .sp -.nf -.ft C - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Reserved |U|S|P|D|I|R| Unix Perm. & Mode | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B The lower 12 bits -hold the common Unix permission and mode bits. An -implementation MAY ignore or interpret these as is suitable on the -host operating system. -.TP -.B Bit 19 ("R") -is set when the file has been deleted. The block list -SHALL be of length zero and the modification time indicates the time -of deletion or, if the time of deletion is not reliably determinable, -the last known modification time. -.TP -.B Bit 18 ("I") -is set when the file is invalid and unavailable for -synchronization. A peer MAY set this bit to indicate that it can -temporarily not serve data for the file. -.TP -.B Bit 17 ("D") -is set when the item represents a directory. The block -list SHALL be of length zero. -.TP -.B Bit 16 ("P") -is set when there is no permission information for the -file. This is the case when it originates on a file system which -does not support permissions. Changes to only permission bits SHOULD -be disregarded on files with this bit set. The permissions bits MUST -be set to the octal value 0666. -.TP -.B Bit 15 ("S") -is set when the file is a symbolic link. The block list -SHALL be of one or more blocks since the target of the symlink is -stored within the blocks of the file. -.TP -.B Bit 14 ("U") -is set when the symbolic links target does not exist. On -systems where symbolic links have types, this bit being means that -the default file symlink SHALL be used. If this bit is unset bit 19 -will decide the type of symlink to be created. -.TP -.B Bit 0 through 13 -are reserved for future use and SHALL be set to -zero. -.UNINDENT +The \fBsize\fP field contains the size of the file, in bytes. For directories +the size is zero. For symlinks the size is the length of the target name. .sp -The \fBModified\fP time is expressed as the number of seconds since the Unix +The \fBpermissions\fP field holds the common Unix permission bits. An +implementation MAY ignore or interpret these as is suitable on the host +operating system. +.sp +The \fBmodified\fP time is expressed as the number of seconds since the Unix Epoch (1970\-01\-01 00:00:00 UTC). .sp -The \fBVersion\fP field is a version vector describing the updates performed -to a file by all members in the cluster. Each counter in the version -vector is an ID\-Value tuple. The ID is used the first 64 bits of the -device ID. The Value is a simple incrementing counter, starting at zero. -The combination of Folder, Name and Version uniquely identifies the -contents of a file at a given point in time. +The \fBdeleted\fP field is set when the file has been deleted. The block list +SHALL be of length zero and the modification time indicates the time of +deletion or, if the time of deletion is not reliably determinable, the last +known modification time. .sp -The \fBLocal Version\fP field is the value of a device local monotonic clock +The \fBinvalid\fP field is set when the file is invalid and unavailable for +synchronization. A peer MAY set this bit to indicate that it can temporarily +not serve data for the file. +.sp +The \fBno permissions\fP field is set when there is no permission information +for the file. This is the case when it originates on a file system which +does not support permissions. Changes to only permission bits SHOULD be +disregarded on files with this bit set. The permissions bits MUST be set to +the octal value 0666. +.sp +The \fBversion\fP field is a version vector describing the updates performed +to a file by all members in the cluster. Each counter in the version vector +is an ID\-Value tuple. The ID is the first 64 bits of the device ID. The +Value is a simple incrementing counter, starting at zero. The combination of +Folder, Name and Version uniquely identifies the contents of a file at a +given point in time. +.sp +The \fBlocal version\fP field is the value of a device local monotonic clock at the time of last local database update to a file. The clock ticks on every local database update. .sp -The \fBBlocks\fP list contains the size and hash for each block in the file. -Each block represents a 128 KiB slice of the file, except for the last -block which may represent a smaller amount of data. -.sp -The hash algorithm is implied by the \fBHash\fP length. Currently, the hash -MUST be 32 bytes long and computed by SHA256. -.SS XDR -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -struct IndexMessage { - string Folder<256>; - FileInfo Files<1000000>; - unsigned int Flags; - Option Options<64>; -}; - -struct FileInfo { - string Name<8192>; - unsigned int Flags; - hyper Modified; - Vector Version; - hyper LocalVersion; - BlockInfo Blocks<10000000>; -}; - -struct Vector { - Counter Counters<>; -}; - -struct Counter { - unsigned hyper ID; - unsigned hyper Value; -}; - -struct BlockInfo { - unsigned int Size; - opaque Hash<64>; -}; -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Request (Type = 2) +The \fBblocks\fP list contains the size and hash for each block in the file. +Each block represents a 128 KiB slice of the file, except for the last block +which may represent a smaller amount of data. +.SS Request .sp The Request message expresses the desire to receive a data block corresponding to a part of a certain file in the peer\(aqs folder. -.SS Graphical Representation +.SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -RequestMessage Structure: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Folder | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Folder (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Name | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Name (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| | -+ Offset (64 bits) + -| | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Size | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Hash | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Hash (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Flags | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Options | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more Option Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +message Request { + int32 id = 1; + string folder = 2; + string name = 3; + int64 offset = 4; + int32 size = 5; + bytes hash = 6; + bool from_temporary = 7; +} .ft P .fi .UNINDENT .UNINDENT .SS Fields .sp -The Folder and Name fields are as documented for the Index message. The -Offset and Size fields specify the region of the file to be transferred. -This SHOULD equate to exactly one block as seen in an Index message. +The \fBid\fP is the request identifier. It will be matched in the +corresponding \fBRequest\fP message. Each outstanding request must have a +unique ID. .sp -The Hash field MAY be set to the expected hash value of the block, or -may be left empty (zero length). If set, the other device SHOULD ensure -that the transmitted block matches the requested hash. The other device -MAY reuse a block from a different file and offset having the same size -and hash, if one exists. +The \fBfolder\fP and \fBname\fP fields are as documented for the Index message. +The \fBoffset\fP and \fBsize\fP fields specify the region of the file to be +transferred. This SHOULD equate to exactly one block as seen in an Index +message. .sp -The \fBFlags\fP field is made up of the following single bit flags: -.INDENT 0.0 -.INDENT 3.5 +The \fIhash\fP field MAY be set to the expected hash value of the block. If set, +the other device SHOULD ensure that the transmitted block matches the +requested hash. The other device MAY reuse a block from a different file and +offset having the same size and hash, if one exists. .sp -.nf -.ft C - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Reserved |T| -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B Bit 31 ("T", Temporary) -is set to indicate that the read should be performed -from the temporary file (converting Name to it\(aqs temporary form) and falling -back to the non temporary file if any error occurs. Knowledge of content -.INDENT 7.0 -.INDENT 3.5 -inside temporary files comes from DownloadProgress messages. -.UNINDENT -.UNINDENT -.UNINDENT -.sp -The Options list is implementation defined and as described in the -ClusterConfig message section. -.SS XDR -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -struct RequestMessage { - string Folder<64>; - string Name<8192>; - hyper Offset; - int Size; - opaque Hash<64>; - unsigned int Flags; - Option Options<64>; -}; -.ft P -.fi -.UNINDENT -.UNINDENT -.SS Response (Type = 3) +The \fBfrom temporary\fP field is set to indicate that the read should be +performed from the temporary file (converting name to it\(aqs temporary form) +and falling back to the non temporary file if any error occurs. Knowledge of +contents of temporary files comes from DownloadProgress messages. +.SS Response .sp The Response message is sent in response to a Request message. -.SS Graphical Representation -.sp -ResponseMessage Structure: +.SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Data | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Data (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Code | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +message Response { + int32 id = 1; + bytes data = 2; + ErrorCode code = 3; +} + +enum ErrorCode { + NO_ERROR = 0; + GENERIC = 1; + NO_SUCH_FILE = 2; + INVALID_FILE = 3; +} .ft P .fi .UNINDENT .UNINDENT .SS Fields .sp -The \fBData\fP field contains either a full 128 KiB block, a shorter block in -the case of the last block in a file, or is empty (zero length) if the -requested block is not available. +The \fBid\fP field is the request identifier. It must match the ID of the +\fBRequest\fP that is being responded to. .sp -The \fBCode\fP field contains an error code describing the reason a Request -could not be fulfilled, in the case where a zero length Data was -returned. The following values are defined: +The \fBdata\fP field contains either the requested data block or is empty if +the requested block is not available. +.sp +The \fBcode\fP field contains an error code describing the reason a Request +could not be fulfilled, in the case where zero length data was returned. The +following values are defined: .INDENT 0.0 .TP .B 0 -No Error (Data should be present) +No Error (data should be present) .TP .B 1 Generic Error @@ -1013,227 +598,126 @@ outside the acceptable range for the file) Invalid (file exists but has invalid bit set or is otherwise unavailable) .UNINDENT -.SS XDR -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -struct ResponseMessage { - opaque Data<>; - int Code; -} -.ft P -.fi -.UNINDENT -.UNINDENT -.SS DownloadProgress (Type = 8) +.SS DownloadProgress .sp The DownloadProgress message is used to notify remote devices about partial availability of files. By default, these messages are sent every 5 seconds, and only in the cases where progress or state changes have been detected. Each DownloadProgress message is addressed to a specific folder and MUST -contain zero or more FileDownloadProgressUpdate structures. -.SS Graphical Representation +contain zero or more FileDownloadProgressUpdate messages. +.SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -DownloadProgressMessage Structure: +message DownloadProgress { + string folder = 1; + repeated FileDownloadProgressUpdate updates = 2; +} - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Folder (length + padded data) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Updates | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more FileDownloadProgressUpdate Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Flags | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Options | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more Option Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +message FileDownloadProgressUpdate { + FileDownloadProgressUpdateType update_type = 1; + string name = 2; + Vector version = 3; + repeated int32 block_indexes = 4; +} -FileDownloadProgressUpdate Structure: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Update Type | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Name (length + padded data) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Version Structure \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Block Indexes | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -| Block Indexes (n items) | -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +enum FileDownloadProgressUpdateType { + APPEND = 0; + FORGET = 1; +} .ft P .fi .UNINDENT .UNINDENT -.sp -Each .SS Fields (DownloadProgress Message) .sp -\fBFolder\fP represents the ID of the folder for which the update is being -provided. +The \fBfolder\fP field represents the ID of the folder for which the update is +being provided. .sp -The \fBFlags\fP field is reserved for future use and MUST currently be set to -zero. The \fBOptions\fP field contains a list of options that apply to the update. -.SS Fields (FileDownloadProgressUpdate Structure) +The \fBupdates\fP field is a list of progress update messages. +.SS Fields (FileDownloadProgressUpdate Message) .sp -The \fBUpdate Type\fP field is made up of the following single bit flags: -.INDENT 0.0 -.INDENT 3.5 +The \fBupdate type\fP indicates whether the update is of type \fBappend (0)\fP +(new blocks are available) or \fBforget (1)\fP (the file transfer has +completed or failed). .sp -.nf -.ft C - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Reserved |F| -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -.ft P -.fi -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B Bit 31 ("F", Forget) -is set to notify that the file that was previously -advertised is no longer available (at least as a temporary file). -.UNINDENT +The \fBname\fP field defines the file name from the global index for which +this update is being sent. .sp -The \fBName\fP field defines the file name from the global index for which this +The \fBversion\fP message defines the version of the file for which this update is being sent. .sp -The \fBVersion\fP structure defines the version of the file for which this update -is being sent. +The \fBblock indexes\fP field is a list of positive integers, where each +integer represents the index of the block in the FileInfo message Blocks +array that has become available for download. .sp -\fBBlock Indexes\fP is a list of positive integers, where each integer represents -the index of the block in the FileInfo structure Blocks array that has become -available for download. -For example an integer with with value 3 represents that the data defined in the -fourth BlockInfo structure of the FileInfo structure of that file is now available. -Please note that matching should be done on \fBName\fP AND \fBVersion\fP\&. -Furthermore, each update received is incremental, for example the initial update -structure might contain indexes 0, 1, 2, an update 5 seconds later might contain -indexes 3, 4, 5 which should be appended to the original list, which implies -that blocks 0\-5 are currently available. +For example an integer with value 3 represents that the data defined in the +fourth BlockInfo message of the FileInfo message of that file is now +available. Please note that matching should be done on \fBname\fP AND +\fBversion\fP\&. Furthermore, each update received is incremental, for example +the initial update message might contain indexes 0, 1, 2, an update 5 +seconds later might contain indexes 3, 4, 5 which should be appended to the +original list, which implies that blocks 0\-5 are currently available. .sp -Block indexes MAY be added in any order. -An implementation MUST NOT assume that block indexes are added in any specific -order. +Block indexes MAY be added in any order. An implementation MUST NOT assume +that block indexes are added in any specific order. .sp -\fBForget\fP bit being set implies that the file that was previously advertised -is no longer available, therefore the list of block indexes should be truncated. +The \fBforget\fP field being set implies that previously advertised file is no +longer available, therefore the list of block indexes should be truncated. .sp -Messages with \fBForget\fP bit set MUST NOT have any block indexes. +Messages with the \fBforget\fP field set MUST NOT have any block indexes. .sp -Any update message which is being sent for a different \fBVersion\fP of the same -file name must be preceded with an update message for the old version of that -file with the \fBForget\fP bit set. +Any update message which is being sent for a different \fBversion\fP of the +same file name must be preceded with an update message for the old version +of that file with the \fBforget\fP field set. .sp -As a safeguard on the receiving side, value of \fBVersion\fP changing between -update messages implies that the file has changed, and that any indexes -previously advertised are no longer available. The list of available block -indexes MUST be replaced (rather than appended) with the indexes specified in -this message. -.SS XDR +As a safeguard on the receiving side, the value of \fBversion\fP changing +between update messages implies that the file has changed and that any +indexes previously advertised are no longer available. The list of available +block indexes MUST be replaced (rather than appended) with the indexes +specified in this message. +.SS Ping +.sp +The Ping message is used to determine that a connection is alive, and to +keep connections alive through state tracking network elements such as +firewalls and NAT gateways. A Ping message is sent every 90 seconds, if no +other message has been sent in the preceding 90 seconds. +.SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -struct DownloadProgressMessage { - string Folder<64>; - FileDownloadProgressUpdate Updates<1000000>; - unsigned int Flags; - Option Options<64>; -} - -struct FileDownloadProgressUpdate { - unsigned int UpdateType; - string Name<8192>; - Vector Version; - int BlockIndexes<1000000>; +message Ping { } .ft P .fi .UNINDENT .UNINDENT -.SS Ping (Type = 4) +.SS Close .sp -The Ping message is used to determine that a connection is alive, and to keep -connections alive through state tracking network elements such as firewalls -and NAT gateways. The Ping message has no contents. A Ping message is sent -every 90 seconds, if no other message has been sent in the preceding 90 -seconds. -.SS Close (Type = 7) -.sp -The Close message MAY be sent to indicate that the connection will be -torn down due to an error condition. A Close message MUST NOT be -followed by further messages. -.SS Graphical Representation +The Close message MAY be sent to indicate that the connection will be torn +down due to an error condition. A Close message MUST NOT be followed by +further messages. +.SS Protocol Buffer Schema .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -CloseMessage Structure: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of Reason | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Reason (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Code | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ +message Close { + string reason = 1; +} .ft P .fi .UNINDENT .UNINDENT .SS Fields .sp -The \fBReason\fP field contains a human description of the error condition, -suitable for consumption by a human. The \fBCode\fP field is for a machine -readable error code. Codes are reserved for future use and MUST -currently be set to zero. -.INDENT 0.0 -.INDENT 3.5 -.sp -.nf -.ft C -struct CloseMessage { - string Reason<1024>; - int Code; -} -.ft P -.fi -.UNINDENT -.UNINDENT +The \fBreason\fP field contains a human readable description of the error +condition. .SH SHARING MODES .SS Trusted .sp @@ -1255,10 +739,10 @@ directions. .UNINDENT .SS Read Only .sp -In read only mode, a device does not apply any updates from the cluster, -but publishes changes of its local folder to the cluster as usual. -The local folder can be seen as a "master copy" that is never affected -by the actions of other cluster devices. +In read only mode, a device does not apply any updates from the cluster, but +publishes changes of its local folder to the cluster as usual. The local +folder can be seen as a "master copy" that is never affected by the actions +of other cluster devices. .INDENT 0.0 .INDENT 3.5 .sp @@ -1275,245 +759,19 @@ by the actions of other cluster devices. .UNINDENT .SH MESSAGE LIMITS .sp -An implementation MAY impose reasonable limits on the length of messages -and message fields to aid robustness in the face of corruption or broken -implementations. These limits, if imposed, SHOULD NOT be more -restrictive than the following. An implementation should strive to keep -messages short and to the point, favouring more and smaller messages -over fewer and larger. For example, favour a smaller Index message -followed by one or more Index Update messages rather than sending a very -large Index message. -.TS -center; -|l|l|l|. -_ -T{ -Message Type -T} T{ -Field -T} T{ -Limit -T} -_ -T{ -\fBAll Messages\fP -T} -_ -T{ -.nf - -.fi -T} T{ -Total length -T} T{ -512 MiB -T} -_ -T{ -\fBIndex and Index Update Messages\fP -T} -_ -T{ -.nf - -.fi -T} T{ -Folder -T} T{ -64 bytes -T} -_ -T{ -.nf - -.fi -T} T{ -Number of Files -T} T{ -1.000.000 -T} -_ -T{ -.nf - -.fi -T} T{ -Name -T} T{ -8192 bytes -T} -_ -T{ -.nf - -.fi -T} T{ -Number of Blocks -T} T{ -10.000.000 -T} -_ -T{ -.nf - -.fi -T} T{ -Hash -T} T{ -64 bytes -T} -_ -T{ -.nf - -.fi -T} T{ -Number of Counters -T} T{ -1.000.000 -T} -_ -T{ -\fBRequest Messages\fP -T} -_ -T{ -.nf - -.fi -T} T{ -Folder -T} T{ -64 bytes -T} -_ -T{ -.nf - -.fi -T} T{ -Name -T} T{ -8192 bytes -T} -_ -T{ -\fBResponse Messages\fP -T} -_ -T{ -.nf - -.fi -T} T{ -Data -T} T{ -256 KiB -T} -_ -T{ -\fBCluster Config Message\fP -T} -_ -T{ -.nf - -.fi -T} T{ -Number of Folders -T} T{ -1.000.000 -T} -_ -T{ -.nf - -.fi -T} T{ -Number of Devices -T} T{ -1.000.000 -T} -_ -T{ -.nf - -.fi -T} T{ -Number of Options -T} T{ -64 -T} -_ -T{ -.nf - -.fi -T} T{ -Key -T} T{ -64 bytes -T} -_ -T{ -.nf - -.fi -T} T{ -Value -T} T{ -1024 bytes -T} -_ -T{ -\fBDownload Progress Messages\fP -T} -_ -T{ -.nf - -.fi -T} T{ -Folder -T} T{ -64 bytes -T} -_ -T{ -.nf - -.fi -T} T{ -Number of Updates -T} T{ -1.000.000 -T} -_ -T{ -.nf - -.fi -T} T{ -Name -T} T{ -8192 bytes -T} -_ -T{ -.nf - -.fi -T} T{ -Number of Indexes -T} T{ -1.000.000 -T} -_ -.TE +An implementation MAY impose reasonable limits on the length of messages and +message fields to aid robustness in the face of corruption or broken +implementations. An implementation should strive to keep messages short +and to the point, favouring more and smaller messages over fewer and larger. +For example, favour a smaller Index message followed by one or more Index +Update messages rather than sending a very large Index message. .sp -The currently defined values allow maximum file size of 1220 GiB -(10.000.000 x 128 KiB). The maximum message size covers an Index message -for the maximum file. +The Syncthing implementation imposes a hard limit of 500,000,000 bytes on +all messages. Attempting to send or receive a larger message will result in +a connection close. This size was chosen to accomodate Index messages +containing a large block list. It\(aqs intended that the limit may be further +reduced in a future protocol update supporting variable block sizes (and +thus shorter block lists for large files). .SH EXAMPLE EXCHANGE .TS center; @@ -1644,15 +902,15 @@ _ .TE .sp The connection is established and at 1. both peers send ClusterConfiguration -messages and then Index records. The Index records are received and both peers -recompute their knowledge of the data in the cluster. In this example, peer A -has four missing or outdated blocks. At 5 through 8 peer A sends requests for -these blocks. The requests are received by peer B, who retrieves the data from -the folder and transmits Response records (9 through 12). Device A updates -their folder contents and transmits an Index Update message (13). Both peers -enter idle state after 13. At some later time 14, the ping timer on device B -expires and a Ping message is sent. The same process occurs for device A at -15. +messages and then Index records. The Index records are received and both +peers recompute their knowledge of the data in the cluster. In this example, +peer A has four missing or outdated blocks. At 5 through 8 peer A sends +requests for these blocks. The requests are received by peer B, who +retrieves the data from the folder and transmits Response records (9 through +12). Device A updates their folder contents and transmits an Index Update +message (13). Both peers enter idle state after 13. At some later time 14, +the ping timer on device B expires and a Ping message is sent. The same +process occurs for device A at 15. .SH EXAMPLES OF STRONG CIPHER SUITES .TS center; diff --git a/man/syncthing-config.5 b/man/syncthing-config.5 index 21c829c4..85967a31 100644 --- a/man/syncthing-config.5 +++ b/man/syncthing-config.5 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-CONFIG" "5" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-CONFIG" "5" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing-config \- Syncthing Configuration . diff --git a/man/syncthing-device-ids.7 b/man/syncthing-device-ids.7 index 92177592..fa83487b 100644 --- a/man/syncthing-device-ids.7 +++ b/man/syncthing-device-ids.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-DEVICE-IDS" "7" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-DEVICE-IDS" "7" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing-device-ids \- Understanding Device IDs . diff --git a/man/syncthing-event-api.7 b/man/syncthing-event-api.7 index 7acbe202..633f7fe6 100644 --- a/man/syncthing-event-api.7 +++ b/man/syncthing-event-api.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-EVENT-API" "7" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-EVENT-API" "7" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing-event-api \- Event API . diff --git a/man/syncthing-faq.7 b/man/syncthing-faq.7 index 5f4b193c..0115bc88 100644 --- a/man/syncthing-faq.7 +++ b/man/syncthing-faq.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-FAQ" "7" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-FAQ" "7" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing-faq \- Frequently Asked Questions . diff --git a/man/syncthing-globaldisco.7 b/man/syncthing-globaldisco.7 index 87cdba34..253d08c3 100644 --- a/man/syncthing-globaldisco.7 +++ b/man/syncthing-globaldisco.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-GLOBALDISCO" "7" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-GLOBALDISCO" "7" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing-globaldisco \- Global Discovery Protocol v3 . diff --git a/man/syncthing-localdisco.7 b/man/syncthing-localdisco.7 index 5a8556c2..781206d2 100644 --- a/man/syncthing-localdisco.7 +++ b/man/syncthing-localdisco.7 @@ -1,8 +1,8 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-LOCALDISCO" "7" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-LOCALDISCO" "7" "July 05, 2016" "v0.13" "Syncthing" .SH NAME -syncthing-localdisco \- Local Discovery Protocol v3 +syncthing-localdisco \- Local Discovery Protocol v4 . .nr rst2man-indent-level 0 . @@ -39,16 +39,19 @@ reply; the only message type is Announcement. On multihomed hosts the announcement packets should be sent on each interface on which Syncthing will accept connections. .sp +The announcement packet is sent over UDP. +.sp For IPv4, the Announcement packet is broadcast either to the link\-specific broadcast address, or to the generic link\-local broadcast address \fB255.255.255.255\fP, with destination port 21027. .sp For IPv6, the Announcement packet is multicast to the transient link\-local -multicast address \fB[ff12::8384]\fP, with destination port 21027. +multicast address \fBff12::8384\fP, with destination port 21027. .sp -It is recommended that local discovery Announcement packets be sent on a 30 to -60 second interval, possibly with immediate transmissions when a previously -unknown device is discovered. +It is recommended that local discovery Announcement packets be sent on a 30 +to 60 second interval, possibly with immediate transmissions when a +previously unknown device is discovered or a device has restarted (see the +\fBinstance_id\fP field). .SH DEVICE ID .sp The device ID is the SHA\-256 (32 bytes) of the device X.509 certificate. See @@ -61,51 +64,13 @@ The Announcement packet has the following structure: .sp .nf .ft C -Announce Structure: - 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ | Magic | +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ / / -\e Device Structure \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Extra Devices | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more Device Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ - -Device Structure: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of ID | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e ID (variable length) \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Number of Addresses | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e Zero or more Address Structures \e -/ / -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ - -Address Structure: - - 0 1 2 3 - 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -| Length of URL | -+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ -/ / -\e URL (variable length) \e +\e Announce Message \e / / +\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+\-+ .ft P @@ -113,46 +78,43 @@ Address Structure: .UNINDENT .UNINDENT .sp -The corresponding XDR representation is as follows (see -\fI\%RFC4506\fP <\fBhttp://tools.ietf.org/html/rfc4506\fP> for the XDR format): +There is no explicit length field as the length is given by the length of +the discovery announcement packet itself. +.sp +The Magic field is a 32 bit word representing 0x2EA7D90B in network (big +endian) byte order. It identifies the packet as being a Syncthing discovery +protocol packet. +.sp +The Announce Message contents are in protocol buffer format using the +following schema: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -struct Announcement { - unsigned int Magic; - Device This; - Device Extra<>; -} - -struct Device { - opaque ID<32>; - Address Addresses<16>; -} - -struct Address { - string URL<2083>; +message Announce { + bytes id = 1; + repeated string addresses = 2; + int64 instance_id = 3; } .ft P .fi .UNINDENT .UNINDENT .sp -In the \fBAnnounce\fP structure field \fBMagic\fP is used to ensure -a correct datagram was received and MUST be equal to \fB0x7D79BC40\fP\&. +The \fBid\fP field contains the Device ID of the sending device. .sp -The first Device structure contains information about the sending -device. The following zero or more Extra devices contain information -about other devices known to the sending device. +The \fBaddresses\fP field contains a list of addresses where the device can be +contacted. Direct connections will typically have the \fBtcp://\fP scheme. +Relay connections will typically use the \fBrelay://\fP scheme. .sp -In the \fBDevice\fP structure, field \fBDeviceID\fP is the SHA\-256 (32 -bytes) of the device X.509 certificate, as explained in section \fIDevice -ID\fP\&. +When interpreting addresses with an unspecified address, e.g., +\fBtcp://0.0.0.0:22000\fP or \fBtcp://:42424\fP, the source address of the +discovery announcement is to be used. .sp -For each \fBAddress\fP the \fBURL\fP field contains the actual target address. -Direct connections will typically have the \fBtcp://\fP scheme. Relay connections -will typically use the \fBrelay://\fP scheme. +The \fBinstance_id\fP field is set to a randomly generated ID at client +startup. Other devices on the network can detect a change in instance ID +between two announces and conclude that the announcing device has restarted. .SH AUTHOR The Syncthing Authors .SH COPYRIGHT diff --git a/man/syncthing-networking.7 b/man/syncthing-networking.7 index bf01cfa0..a732a7a6 100644 --- a/man/syncthing-networking.7 +++ b/man/syncthing-networking.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-NETWORKING" "7" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-NETWORKING" "7" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing-networking \- Firewall Setup . diff --git a/man/syncthing-relay.7 b/man/syncthing-relay.7 index e4b1ce1c..a4852e2d 100644 --- a/man/syncthing-relay.7 +++ b/man/syncthing-relay.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-RELAY" "7" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-RELAY" "7" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing-relay \- Relay Protocol v1 . diff --git a/man/syncthing-rest-api.7 b/man/syncthing-rest-api.7 index a826595a..142ffc14 100644 --- a/man/syncthing-rest-api.7 +++ b/man/syncthing-rest-api.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-REST-API" "7" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-REST-API" "7" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing-rest-api \- REST API . diff --git a/man/syncthing-security.7 b/man/syncthing-security.7 index 79d12fae..978d000f 100644 --- a/man/syncthing-security.7 +++ b/man/syncthing-security.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-SECURITY" "7" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-SECURITY" "7" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing-security \- Security Principles . diff --git a/man/syncthing-stignore.5 b/man/syncthing-stignore.5 index 95f9596e..2747c997 100644 --- a/man/syncthing-stignore.5 +++ b/man/syncthing-stignore.5 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING-STIGNORE" "5" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING-STIGNORE" "5" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing-stignore \- Prevent files from being synchronized to other nodes . diff --git a/man/syncthing-versioning.7 b/man/syncthing-versioning.7 index bf54d71c..3c035004 100644 --- a/man/syncthing-versioning.7 +++ b/man/syncthing-versioning.7 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "TODO" "7" "July 02, 2016" "v0.13" "Syncthing" +.TH "TODO" "7" "July 05, 2016" "v0.13" "Syncthing" .SH NAME Todo \- Keep automatic backups of deleted files by other nodes . diff --git a/man/syncthing.1 b/man/syncthing.1 index a548f079..6cdc73b6 100644 --- a/man/syncthing.1 +++ b/man/syncthing.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "SYNCTHING" "1" "July 02, 2016" "v0.13" "Syncthing" +.TH "SYNCTHING" "1" "July 05, 2016" "v0.13" "Syncthing" .SH NAME syncthing \- Syncthing .