nextcloud-desktop/doc/navigating.rst

Using the Synchronization Client
================================

.. index:: navigating, usage

The ownCloud Client remains in the background and is visible as an icon in the
system tray (Windows, KDE), status bar (MAC OS X), or notification area
(Ubuntu).

.. image:: images/icon.png

**ownCloud Desktop Client icon**

Using the Desktop Client Menu
-----------------------------

A right click on the icon (left click on Ubuntu and Mac OS X) provides the
following menu:

.. image:: images/menu.png

**ownCloud Desktop Client menu**

The Desktop Client menu provides the following options:

* ``Open ownCloud in browser``: Launches the ownCloud WEB interface.
* ``Open folder 'ownCloud'``: Opens the ownCloud local folder.  If you have defined multiple synchronization targets, the window displays each local folder.
* **Disk space indicator**: Indicates the amount of space currently used on the server.
* Operation indicator: Displays the status of the current synchronization process or indicates ``Up to date`` if the server and client are in sync.
* **Recent Changes**: Displays the last six files modified by the synchronization operations and provides access to the current synchronization status listing all changes since the last restart of the ownCloud client.
* ``Settings...``: Provides access to the settings menu.
* ``Help``: Opens a browser to display ownCloud Desktop Client Guide.
* ``Sign out``: Disables the client from continued synchronizations.
* ``Quit ownCloud``: Quits the ownCloud Client, ending any currently running
  synchronizations.

Using the Account Settings Window
---------------------------------

.. index:: account settings, user, password, Server URL

The ``Account`` window provides a summary for general settings associated with the ownCloud account.  This window enalbes you to manage any synchronized folders in the account and enables you to modify them.

To access and modify the account settings:

.. image:: images/settings_account.png
   :scale: 50 %

The fields and options in this window include:

* ``Connected to <ownCloud instance> as <user>`` field:  Indicates the ownCloud server to which the client is synchronizing and the user account on that server.

* ``Add Folder...`` button: Provides the ability to add another folder to the synchronization process (see ``Adding a Folder``).

* ``Pause/Resume`` button: Pauses the current sync (or prevents the client from starting a new sync) or resumes the sync process.

* ``Remove`` button: Removes the selected folder from the sync process.  This button is used when you want to synchronize only a few folders and not the root folder.  If only the root folder is available, you must first remove the root from the synchronization and then add individual folders that you want to synchronize as desired.

* ``Storage Usage`` field: Indicates the storage utilization on the ownCloud server.

* ``Edit Ignored Files`` button: Launches the Ignored Files Editor.

* ``Modify Account`` button: Enables you to change the ownCloud server to which you are synchronizing. This option launches the ``Setting up an Account`` windows (See ??).


Adding a Folder
^^^^^^^^^^^^^^^

The ``Add a Folder ...`` button enables you to add a new folder to the syncrhonization process.

To add a new folder:

1. Click the ``Add a Folder ...`` button in the Account window.

  The ``Add Folder...`` window opens

  .. image:: images/folderwizard_local.png
   :scale: 50 %

   **``Add Folder...`` window (local folder)**

2. Specify a *unique* path and alias name to the folder or use the ``Choose...`` button to locate the new folder on your system to which you want to synchronize.

  ..note:: Nested synchronizations are not supported.  In other words, you
    cannot add a folder that is already contained within another synchronized
    folder. In addition, you cannot add a higher level (parent) folder that
    contains a folder to which you are already synchronizing.  By default, the
    ownCloud Set Up Wizard syncrhonizes your entire ownCloud account to the root
    folder of the ownCloud server. Due to this default setup, you must first remove
    the top-level folder prior to specifying new synchronizations.

3. Click 'Next' to continue.

  A window opens prompting you to select a remote destination folder on the
  ownCloud server to which you want to synchronize.

   .. image:: images/folderwizard_remote.png
   :scale: 50 %

   **``Add Folder...`` window (remote destination)**

4. Select a folder on the ownCloud server to which you want to synchronize your newly added folder.

  ..note:: A server folder can only be synchronized with a particular client once.
    If you attempt to sync the root directory, you cannot sync with other folders
    on the server. Similarly, if you sync with folder ``/a``, you cannot create
    another sync with ``/a/b``, since ``b`` is already being synched.

Editing Ignored Files
^^^^^^^^^^^^^^^^^^^^^

The :guilabel:`Ignored Files Editor` provides a list of preconfigured files
that are ignored (that is, not synchronized) by the client and server during
synchronizations. The Ignored Files Editor enables you to add patterns for
files or directories that you want to exclude from the synchronization process.
In addition to using standard characters, the Ignored Files Editor enables you
to use wild cards (for example, using an asterisk ‘*’ to indicate multiple
characters or a question mark ‘?’ to incidate a single character).

For additional information about this editor, see `Using the Ignored Files Editor`_

Using the Activity Settings Window
----------------------------------

.. index:: activity, recent changes, sync activity

The Activity window provides an in-depth account of recent synchronization
activity.  It shows files that have not been synchronized because they are on
the ignored files list or because they cannot be synced in a cross-platform
manner due to containing special characters that cannot be stored on certain
file systems.

.. image:: images/settings_activity.png
   :scale: 50 %

   **Activity settings window**

You can open the Activity window in one of the following ways:

- Click 'Activity' in the left frame of the ownCloud Settings window.

- Invoke the window from the ownCloud Desktop Client menu by selecting ``Recent
  Changes`` > ``Details...``.  (See Using the Desktop Client Menu.) 

Using the General Settings Window
---------------------------------

.. index:: general settings, auto start, startup, desktop notifications

The General settings window enables you to set general settings for the
ownCloud Desktop Client and provides information about the software version,
its creator, and the existance of any updates.

.. image:: images/settings_general.png
   :scale: 50 %

   **General settings window**

The settings and information contained in this window are as follows:

* ``Launch on System Startup`` checkbox: Provides the option to check (enable)
  or uncheck (disable) whether the ownCloud Desktop Client launches upon system
  startup.  By default, this option is enabled (checked)once you have configured
  your account.

* ``Show Desktop Nofications`` checkbox: Provides the option to check (enable)
  or uncheck (disable) bubble notifications alerting you as to when a set of
  synchronization operations is performed.

* ``Use Monochrome Icons`` checkbox: Provides the option to check (enable) or
   uncheck (disable) the use of monochrome (visually less obtrusive) icons.

  .. note:: This option can be useful on MAC OSX platforms.

* ``About`` field: Provides information about the software authors along with
  pertinent build conditions.

  .. note:: Information in this field can be valuable when submitting a support request.

* ``Updates`` field: Provides information about any available updates for the
  ownCloud Desktop Client.

Using the Network Settings Window
---------------------------------

.. index:: proxy settings, SOCKS, bandwith, throttling, limiting

The Network settings window enables you to define network proxy settings as
well as limit the download and upload bandwidth utilization of file
synchronizations.

.. image:: images/settings_network.png
   :scale: 50 %

   **Network settings window**

Specifying Proxy Settings
^^^^^^^^^^^^^^^^^^^^^^^^^

A proxy server is a server (for example, a computer system or an application)
that functions as an intermediary contact for requests from clients that are
seeking resources from other servers.  For the ownCloud Desktop Client, you can
define the following proxy settings:

* ``No Proxy`` option: Specifies that the ownCloud Client circumvent the default proxy configured on the system.
* ``Use system proxy`` option: Default setting. Follows the systems proxy
  settings. On Linux systems, this setting uses the value of the variable
  ``http_proxy``.
* ``Specify proxy manually as`` option: Enables you to specify
  the following custom proxy settings:
  - ``HTTP(S)``: Used when you are required to use an HTTP(S) proxy server (for example, Squid or Microsoft Forefront TMG). 
  - ``SOCKSv5``: Typically used in special company LAN setups, or in combination with the OpenSSH
  dynamic application level forwarding feature (see ``ssh -D``).
  - ``Host``: Host name or IP address of the proxy server along with the port number. HTTP proxies
    typically listen over Ports 8080 (default) or 3128. SOCKS servers typically listen over port 1080.
* ``Proxy Server requires authentication`` checkbox: Provides the option to check (enable/require) or
  uncheck (disable/not require) proxy server authentication. When not checked, the proxy server must
  be configured to allow anonymous usage. When checked, a proxy server username and password is required.

Bandwidth Limiting
^^^^^^^^^^^^^^^^^^

Synchronization of files between a client and server can utilized a lot of
bandwidth.  Bandwidth limiting can assist in shaping the total download or
upload bandwidth (or both) of your client/server connection to a more
manageable level. By limiting your bandwidth usage, you can maintain free
bandwidth for other applications to use.

The ownCloud Desktop Client enables you to limit (throttle) the bandwidth usage
for both file downloads and file uploads.  The Download Bandwidth field (for
data flowing from the ownCloud server to the client) provides the following
options:

- ``No limit`` option: The default setting for the client; specifies that there
  are no limit settings on the amount of data downloaded from the server. 

- ``Limit to <value> KBytes/s`` option: Limits (throttles) the bandwidth to
  a customized value (in KBytes/second).

The Upload Bandwidth field (for data flowing from the ownCloud client to the
server) provides the following options:

- ``No limit`` option: The default setting for the client; specifies that there
  are no limit settings on the amount of data downloaded from the server. 

- ``Limit automatically``: When enabled, the ownCloud client surrenders
  available bandwidth to other applications.  Use this option if there are
  issues with real time communication (for example, the use of IP phone or live
  streaming) in conjunction with the ownCloud Client.

- ``Limit to <value> KBytes/s`` option: Limits (throttles) the bandwidth to a
  customized value (in KBytes/second).


.. _ignoredFilesEditor-label:

Using the Ignored Files Editor
------------------------------

.. index:: ignored files, exclude files, pattern

You might have some files or directories that you do not want to backup and
store on the server. To identify and exclude these files or directories, you
can use the *Ignored Files Editor* that is embedded in the ownCloud Desktop
Client.

.. image:: images/ignored_files_editor.png
   :scale: 50%

   Ignored Files Editor window

The :guilabel:`Ignored Files Editor` enables you to define customized patterns that the
ownCloud Client uses to identify files and directories that you want to exclude
from the synchronization process. For your convenience, the editor is
pre-populated with a default list of typically ignore patterns. These patterns
are contained in a system file (typically ``sync-exclude.lst``) located in the
ownCloud Client application directory. You cannot modify these pre-populated
patterns directly from the editor. However, if necessary, you can hover over
any pattern in the list to show the path and filename associated with that
pattern, locate the file, and edit the ``sync-exclude.lst`` file.

.. note:: Modifying the global exclude definition file might render the client
   unusable or result in undesired behavior.

Each line in the editor contains an ignore pattern string. When creating custom
patterns, in addition to being able to use normal characters to define an
ignore pattern, you can use wildcards characters for matching values.  As an
example, you can use an asterisk (``*``) to idenfify an arbitrary number of
characters or a question mark (``?``) to identify a single character. 

Patterns that end with a slash character (``/``) are applied to only directory
components of the path being checked.

.. note:: Custom entries are currently not validated for syntactical
   correctness by the editor, but might fail to load correctly.

Each pattern string in the list is preceded by a checkbox. When the check box
contains a check mark, in addition to ignoring the file or directory component
matched by the pattern, any matched files are also deemed "fleeting metadata"
and removed by the client.

In addition to excluding files and directories that use patterns defined in
this list:

- The ownCloud Client always excludes files containing characters that cannot
  be synchronized to other file systems.

- As of ownCloud Desktop Client version 1.5.0, files are removed that cause
  individual errors three times during a synchronization. However, the client
  provides the option of retrying a synchronization three additional times on
  files that produce errors.

For more detailed information see :ref:`ignored-files-label`.