mirror of https://github.com/nextcloud/desktop
Doc: Introduce chapter on Architecture, Glossary
This commit is contained in:
Daniel Molkentin
parent
855597bfd9
commit
8b60726a48
|
|
@ -0,0 +1,108 @@
|
|||
Architecture
|
||||
============
|
||||
.. index:: architecture
|
||||
|
||||
The ownCloud project provides desktop sync clients to synchronize the
|
||||
contents of local directories on the desktop machines to the ownCloud.
|
||||
|
||||
The syncing is done with csync_, a bidirectional file synchronizing tool which
|
||||
provides both a command line client as well as a library. A special module for
|
||||
csync was written to synchronize with ownCloud’s built-in WebDAV server.
|
||||
|
||||
The ownCloud sync client is based on a tool called mirall initially written by
|
||||
Duncan Mac Vicar. Later Klaas Freitag joined the project and enhanced it to work
|
||||
with ownCloud server. Both mirall and ownCloud Client (oCC) build from the same
|
||||
source, currently hosted in the ownCloud source repo on gitorious.
|
||||
|
||||
oCC is written in C++ using the `Qt Framework`_. As a result oCC runs on the
|
||||
three important platforms Linux, Windows and MacOS.
|
||||
|
||||
.. _csync: http://www.csync.org
|
||||
.. _`Qt Framework`: http://www.qt-project.org
|
||||
|
||||
The Sync Process
|
||||
----------------
|
||||
|
||||
First it is important to recall what syncing is. Syncing tries to keep the files
|
||||
on both repositories the same. That means if a file is added to one repository
|
||||
it is going to be copied to the other repository. If a file is changed on one
|
||||
repository, the change is propagated to the other repository. Also, if a file
|
||||
is deleted on one side, it is deleted on the other. As a matter of fact, in
|
||||
ownCloud syncing we do not have a typical client/server system where the
|
||||
server is always master.
|
||||
|
||||
This is the major difference to other systems like a file backup where just
|
||||
changes and new files are propagated but files never get deleted.
|
||||
|
||||
Sync Direction and Strategies
|
||||
-----------------------------
|
||||
.. index:: time stamps, file times, etag, unique id
|
||||
|
||||
Until the release of ownCloud 4.5 and ownCloud Client 1.1, ownCloud employed
|
||||
a single file property to decide which file is newer and hence needs to be
|
||||
synced to the other repository: the files modification time.
|
||||
|
||||
The *modification timestamp* is part of the files metadata. It is available on
|
||||
every relevant filesystem and is the natural indicator for a file change.
|
||||
modification timestamps do not require special action to create and have
|
||||
a general meaning. One design goal of csync is to not require a special server
|
||||
component, that’s why it was chosen as the backend component.
|
||||
|
||||
To compare the modification times of two files from different systems,
|
||||
it is needed to operate on the same base. Before version 1.1.0,
|
||||
csync requires both sides running on the exact same time, which can
|
||||
be achieved through enterprise standard `NTP time synchronisation`_ on all
|
||||
machines.
|
||||
|
||||
Since this strategy is rather fragile without NTP, ownCloud 4.5 introduced a
|
||||
unique number, which changes whenever the file changes. Although it is a unique
|
||||
value, it is not a hash of the file, but a randomly chosen number, which it will
|
||||
transmit in the Etag_ field. The client will store this number in a
|
||||
per-directory database, located in the application directory (version 1.1) or
|
||||
as a hidden file right in the directory to be synced (later versions).
|
||||
Since the file number is guaranteed to change if the file changes, it can now be
|
||||
used to determine if one of the files has changed.
|
||||
|
||||
.. todo:: describe what happens if both sides change
|
||||
|
||||
If the per-directory database gets removed, oCC's CSync backend will fall back
|
||||
to a time-stamp based sync process to rebuild the database. Thus it should be
|
||||
made sure that both server and client synchronized to NTP time before
|
||||
restarting the client after a database removal. If time deviates, the sync
|
||||
process might create faux conflict files, which only differ in their time.
|
||||
Those need to be cleaned up manually later on and will not be synced back
|
||||
to the server. However, no files will get deleted in this process.
|
||||
|
||||
Just like files, directories also hold a unique id, which changes whenever
|
||||
one of the contained files or directories gets modified. Since this is a
|
||||
recursive process, it significantly reduces the effort required for a sync
|
||||
cycle, because the client will only walk directories with a modified unique id.
|
||||
|
||||
.. note:: oCC 1.1 and newer require file ID capabilities on the ownCloud server,
|
||||
hence using them with a server earlier than 4.5.0 is not supported.
|
||||
|
||||
This table outlines the different sync methods attempted depending
|
||||
on server/client combination:
|
||||
|
||||
.. index:: compatiblity table
|
||||
|
||||
+--------------------+-------------------+----------------------------+
|
||||
| Server Version | Client Version | Sync Methods |
|
||||
+====================+===================+============================+
|
||||
| 4.0.x or earlier | 1.0.5 or earlier | Time Stamp |
|
||||
+--------------------+-------------------+----------------------------+
|
||||
| 4.0.x or earlier | 1.1 or later | n/a (incompatible) |
|
||||
+--------------------+-------------------+----------------------------+
|
||||
| 4.5 or later | 1.0.5 or earlier | Time Stamp |
|
||||
+--------------------+-------------------+----------------------------+
|
||||
| 4.5 or later | 1.1 or later | File ID, Time Stamp |
|
||||
+--------------------+-------------------+----------------------------+
|
||||
|
||||
It is highly recommended to upgrade to ownCloud 4.5 or later with ownCloud
|
||||
Client 1.1 or later, since the time stamp-based sync mechanism can
|
||||
lead to data loss in certain edge-cases, especially when multiple clients
|
||||
are involved and one of them is not in sync with NTP time.
|
||||
|
||||
.. _`NTP time synchronisation`: http://en.wikipedia.org/wiki/Network_Time_Protocol
|
||||
.. _Etag: http://en.wikipedia.org/wiki/HTTP_ETag
|
||||
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
Branding the ownCloud Client
|
||||
============================
|
||||
Adding 3rd-Party Branding
|
||||
=========================
|
||||
|
||||
The ownCloud Client supports theming in the setup assistant dialog in both the
|
||||
account setting and the result window. These customizations do not require a
|
||||
|
|
|
|||
|
|
@ -0,0 +1,28 @@
|
|||
Glossary
|
||||
========
|
||||
|
||||
.. glossary::
|
||||
:sorted:
|
||||
|
||||
ownCloud Client
|
||||
oCC
|
||||
Name of the official ownCloud syncing client for desktop, which runs on
|
||||
Windows, Mac OS X and Linux. It is based Mirall, and uses the CSync
|
||||
sync engine for synchronization with the ownCloud server.
|
||||
|
||||
ownCloud Server
|
||||
The server counter part of ownCloud Client as provided by the ownCloud
|
||||
community.
|
||||
|
||||
mtime
|
||||
modification time
|
||||
file modification time
|
||||
File property used to determine whether the servers' or the clients' file
|
||||
is more recent. Standard procedure in oCC 1.0.5 and earlier, used by
|
||||
oCC 1.1 and later only when no sync database exists and files already
|
||||
exist in the client directory.
|
||||
|
||||
unique id
|
||||
ID assigned to every file starting with ownCloud server 4.5 and submitted
|
||||
via the HTTP ``Etag``. Used to check if files on client and server have
|
||||
changed.
|
||||
|
|
@ -16,9 +16,11 @@ Contents
|
|||
usage
|
||||
building
|
||||
branding
|
||||
architecture
|
||||
glossary
|
||||
|
||||
.. Indices and tables
|
||||
.. ==================
|
||||
Index
|
||||
=====
|
||||
|
||||
* :ref:`genindex`
|
||||
|
||||
.. * :ref:`genindex`
|
||||
.. * :ref:`modindex`
|
||||
|
|
|
|||
|
|
@ -1,37 +1,21 @@
|
|||
Sync Client Usage
|
||||
=================
|
||||
Usage
|
||||
=====
|
||||
.. index:: usage, client sync usage
|
||||
|
||||
First it is important to recall what syncing is. Syncing tries to keep the files on both repositories the same. That means if a file is added to one repository it is going to be copied to the other repository. If a file is changed on one repository, the change is propagated to the other repository. And also, if a file is deleted on one side, it is deleted on the other. As a matter of fact, in ownCloud syncing we do not have a typical client/server system where the server is always master.
|
||||
To start ownCloud Client, click on the desktop icon or start it from the
|
||||
application menu. In the system tray, an ownCloud icon appears.
|
||||
|
||||
This is the major difference to other systems like a file backup where just changes and new files are propagated but never something is deleted.
|
||||
|
||||
CSync uses file times
|
||||
=====================
|
||||
.. index:: time stamps, file times
|
||||
.. todo:: No longer true
|
||||
|
||||
To decide which file is newer and needs to be synced to the other repository, csync, the underlying sync engine, uses the files modification times.
|
||||
|
||||
The modification timestamp is part of the files metadata. It is available on every relevant filesystem and is the natural indicator for a file change.
|
||||
|
||||
It does not require special action to create and has a general meaning. One design goal of csync is to not require a special server component, that’s why it was used.
|
||||
|
||||
To compare the modification times of two files from different systems, it is needed to operate on the same base. Before version 1.1.0, csync requires both sides running on the exact same time, which can be achieved through enterprise standard ntp time synchronisation [1] on all machines.
|
||||
|
||||
Start ownCloud client
|
||||
=====================
|
||||
.. index:: start application
|
||||
|
||||
To start ownCloud Client, click on the desktop icon or start it from the application menu. In the system tray, an ownCloud icon appears.
|
||||
|
||||
A left click on the tray icon open a status dialog which gives an overview on the configured sync folders and allows to add and remove more sync folder connections as well as pausing a sync connection.
|
||||
A left click on the tray icon open a status dialog which gives an overview on
|
||||
the configured sync folders and allows to add and remove more sync folder
|
||||
connections as well as pausing a sync connection.
|
||||
|
||||
A right click on the tray icon gives other configuration options.
|
||||
|
||||
|
||||
Command line switches
|
||||
=====================
|
||||
---------------------
|
||||
.. index:: command line switches, command line, options, parameters
|
||||
|
||||
|
||||
|
|
@ -48,7 +32,7 @@ ownCloud Client supports the following command line switches:
|
|||
+--------------------------+------------------------------------------------+
|
||||
|
||||
Config File
|
||||
===========
|
||||
-----------
|
||||
.. index:: config file
|
||||
|
||||
ownCloud Client reads a configuration file which on Linux can be found at ``$HOME/.local/share/data/ownCloud/owncloud.cfg``
|
||||
|
|
|
|||
Loading…
Reference in New Issue