From d7dce86f37450987e1a51b27ee3dbde461c7bff9 Mon Sep 17 00:00:00 2001 From: Robin McCorkell Date: Sun, 20 Sep 2015 19:27:34 +0100 Subject: [PATCH] Re-vamp external storage backends --- .../external_storage/amazons3.rst | 25 ++++----- .../external_storage/dropbox.rst | 3 + .../external_storage/ftp.rst | 23 ++++---- .../external_storage/google.rst | 4 ++ .../external_storage/local.rst | 16 ++---- .../external_storage/openstack.rst | 26 +++++---- .../external_storage/owncloud.rst | 5 ++ .../external_storage/sftp.rst | 20 +++++-- .../external_storage/smb.rst | 55 +++++++++---------- .../external_storage/webdav.rst | 21 ++++--- 10 files changed, 108 insertions(+), 90 deletions(-) diff --git a/admin_manual/configuration_files/external_storage/amazons3.rst b/admin_manual/configuration_files/external_storage/amazons3.rst index 8b0193294..139e0d549 100644 --- a/admin_manual/configuration_files/external_storage/amazons3.rst +++ b/admin_manual/configuration_files/external_storage/amazons3.rst @@ -2,22 +2,21 @@ Amazon S3 ========= -All you need to connect your Amazon S3 buckets to ownCloud is your S3 Access -Key, Secret Key, and your bucket name. +To connect your Amazon S3 buckets to ownCloud, you will need: -In the ``Folder name`` field enter the folder name that you want to appear on -your ownCloud ``Files`` page. +- S3 access key +- S3 secret key +- Bucket name -In the ``Access Key`` field enter your S3 Access Key. +Optionally, you can override the hostname, port and region of your S3 server, +which is required for non-Amazon servers such as Ceph Object Gateway. -In the ``Secret Key`` field enter your S3 Secret Key. +The ``Enable SSL`` checkbox enables HTTPS connections. -In the ``Bucket`` field enter the name of your S3 bucket you want to share. - -In the ``Available for`` field enter the users or groups who have permission to -access your S3 mount. - -The hostname, port, and region of your S3 server are optional; you will need -to use these for non-Amazon S3-compatible servers. +``Enable path style`` is usually not required (and is, in fact, incompatible +with newer Amazon datacenters), but can be used with non-Amazon servers where +the DNS infrastructure cannot be controlled. Ordinarily, requests will be +made with ``http://bucket.hostname.domain/``, but with path style enabled, +requests are made with ``http://hostname.domain/bucket`` instead. .. figure:: images/amazons3.png diff --git a/admin_manual/configuration_files/external_storage/dropbox.rst b/admin_manual/configuration_files/external_storage/dropbox.rst index a045c8d5b..65c6d8483 100644 --- a/admin_manual/configuration_files/external_storage/dropbox.rst +++ b/admin_manual/configuration_files/external_storage/dropbox.rst @@ -2,6 +2,9 @@ Dropbox ======= +While Dropbox supports the newer OAuth 2.0, ownClou uses OAuth 1.0, so you can +safely ignore any references to OAuth 2.0 in the Dropbox configuration. + Connecting Dropbox is a little more work because you have to create a Dropbox app. Log into the `Dropbox Developers page `_ and click ``App Console``: diff --git a/admin_manual/configuration_files/external_storage/ftp.rst b/admin_manual/configuration_files/external_storage/ftp.rst index 8d81e0d8a..f78bf4c39 100644 --- a/admin_manual/configuration_files/external_storage/ftp.rst +++ b/admin_manual/configuration_files/external_storage/ftp.rst @@ -2,19 +2,18 @@ FTP === -Connecting to an FTP server requires: +To connect to an FTP server, you will need: -* Whatever name you want for your local mountpoint. -* The URL of your FTP server, and optionally the port number. -* FTP server username and password. -* Remote Subfolder, the FTP directory to mount in ownCloud. ownCloud defaults to the root - directory. When you specify a different directory you must leave off the - leading slash. For example, if you want to connect your - ``public_html/images`` directory, then type it exactly like that. -* Choose whether to connect in the clear with ``ftp://``, or to encrypt your - FTP session with SSL/TLS over ``ftps://`` (Your FTP server must be - configured to support ``ftps://``) -* Enter the ownCloud users or groups who are allowed to access the share. +- The hostname of the FTP server +- Port (default: 21) + +FTP uses the password authentication scheme, see :doc:`auth_mechanisms` + +Optionally, ownCloud can use FTPS by selecting ``Secure ftps://``. This +requires additional configuration with root certificates if the FTP server uses +a self-signed certificate. + +A specific directory can be configured with ``Remote Subfolder``. .. note:: The external storage ``FTP/FTPS`` needs the ``allow_url_fopen`` PHP setting to be set to ``1``. When having connection problems make sure that it is diff --git a/admin_manual/configuration_files/external_storage/google.rst b/admin_manual/configuration_files/external_storage/google.rst index 61e424bc5..96af2b3e7 100644 --- a/admin_manual/configuration_files/external_storage/google.rst +++ b/admin_manual/configuration_files/external_storage/google.rst @@ -2,6 +2,10 @@ Google Drive ============ +ownCloud uses OAuth 2.0 to connect to Google Drive. This requires configuration +through Google to get an app ID and app secret, as ownCloud registers itself +as an app. + All applications that access a Google API must be registered through the `Google Cloud Console `_. Follow along carefully because the Google interface is a bit of a maze and it's easy to get lost. diff --git a/admin_manual/configuration_files/external_storage/local.rst b/admin_manual/configuration_files/external_storage/local.rst index 49130b587..d727a06dd 100644 --- a/admin_manual/configuration_files/external_storage/local.rst +++ b/admin_manual/configuration_files/external_storage/local.rst @@ -2,17 +2,11 @@ Local ===== -Use this to mount any directory on your ownCloud server that is outside of your -ownCloud ``data/`` directory. This directory must be readable and writable by -your HTTP server user. +Local storages provide access to any directory on the ownCloud server. Since +this is a significant security risk, Local storage can only be configured in +the admin settings. -In the ``Folder name`` field enter the folder name that you want to appear on -your ownCloud ``Files`` page. - -In the ``Configuration`` field enter the full filepath of the directory you -want to mount. - -In the ``Available for`` field enter the users or groups who have permission to -access the mount. +The directory will be accessed as the web server user, so permissions must be +correct. .. figure:: images/local.png diff --git a/admin_manual/configuration_files/external_storage/openstack.rst b/admin_manual/configuration_files/external_storage/openstack.rst index 98d79f28a..93df171a3 100644 --- a/admin_manual/configuration_files/external_storage/openstack.rst +++ b/admin_manual/configuration_files/external_storage/openstack.rst @@ -2,15 +2,19 @@ OpenStack Object Storage ======================== -Use this to mount a container on an OpenStack Object Storage server. You need -the following information: +OpenStack Object Storage can be used to connect to an OpenStack Swift server. +Two authentication mechanisms are available, one is the generic 'OpenStack' +mechanism, the other is used exclusively for Rackspace, a provider of object +storage that uses the OpenStack Swift protocol. -* Username -* Bucket -* Region -* API Key -* Tenantname -* Password -* Service Name -* URL of identity Endpoint -* Timeout of HTTP request +The bucket will be created if it does not exist. + +The 'OpenStack' authentication mechanism uses the OpenStack Keystone v2 +protocol, connecting to the server specified in ``Identity Endpoint URL``. +A ``Username``, ``Tenant name`` and ``Password`` are required. + +The 'Rackspace' authentication mechanism requires a Rackspace ``Username`` and +``API key``. + +It may be necessary to specify a ``Service name`` or ``Region``. The timeout of +HTTP requests can be set with the ``Request timeout`` field. diff --git a/admin_manual/configuration_files/external_storage/owncloud.rst b/admin_manual/configuration_files/external_storage/owncloud.rst index 6c40b8f7e..9b338f408 100644 --- a/admin_manual/configuration_files/external_storage/owncloud.rst +++ b/admin_manual/configuration_files/external_storage/owncloud.rst @@ -5,3 +5,8 @@ ownCloud An ownCloud storage is a specialized :doc:`webdav` storage, with optimizations for ownCloud-ownCloud communication. See the :doc:`webdav` documentation for how to configure an ownCloud external storage. + +When filling in the ``URL`` field, put the path to the root of the ownCloud +installation, rather than the path to the WebDAV endpoint. So, for a server at +``http://example.com/owncloud``, put ``http://example.com/owncloud``, not +``http://example.com/owncloud/remote.php/webdav``. diff --git a/admin_manual/configuration_files/external_storage/sftp.rst b/admin_manual/configuration_files/external_storage/sftp.rst index 2b3c4b4b0..ab930a5f2 100644 --- a/admin_manual/configuration_files/external_storage/sftp.rst +++ b/admin_manual/configuration_files/external_storage/sftp.rst @@ -2,10 +2,18 @@ SFTP ==== -To connect an SFTP server you need: +This backend can be used to connect to an SFTP server. -* Whatever name you want for your local mountpoint. -* The URL of your SFTP server. -* SFTP server username and password. -* Remote Subfolder, the SFTP directory to mount in ownCloud. -* The ownCloud users or groups who are allowed to access the share. +A ``Host`` is required; a port can be specified as part of the ``Host`` field +in the following format: ``hostname.domain:port``. The default port is 22 (SSH). + +SFTP supports the password authentication mechanism. See +:doc:`auth_mechanisms` for detailed information. + +SFTP also supports public key authentication. A public/private keypair can be +generated on the ownCloud server, then you need to put the public key on the +destination server in ``.ssh/authorized_keys``. ownCloud will then use the +private key to connect to the SFTP server. + +A ``Root`` can be specified to change the directory used. The default is the +root directory (``/``). diff --git a/admin_manual/configuration_files/external_storage/smb.rst b/admin_manual/configuration_files/external_storage/smb.rst index 912d79df1..9ada9e4b5 100644 --- a/admin_manual/configuration_files/external_storage/smb.rst +++ b/admin_manual/configuration_files/external_storage/smb.rst @@ -2,35 +2,34 @@ SMB/CIFS ======== -You can mount SMB/CIFS file shares on ownCloud servers that run on Linux. This -requires ``php5-libsmbclient`` (`installation instructions -`_). SMB/CIFS file servers include any Windows -file share, Samba servers on Linux and other Unix-type operating systems, and -NAS appliances. +ownCloud can connect to Windows file servers or other SMB compatible servers +with this backend. -You need the following information: +.. note:: The SMB/CIFS backend requires ``smbclient`` to be installed on the + ownCloud server. This is a utility provided as part of the Samba + project. -* Folder name -- Whatever name you want for your local mountpoint. -* Host -- The URL of the Samba server. -* Username -- The username or domain/username used to login to the Samba server. -* Password -- The password to login to the Samba server. -* Share -- The share on the Samba server to mount. -* Remote Subfolder -- The remote subfolder inside the Samba share to mount - (optional, defaults to ``/``). To assign the ownCloud logon username - automatically to the subfolder, use ``$user`` instead of a particular - subfolder name. And finally, the ownCloud users and groups who get access - to the share. +The following information is required: + +- ``Host`` -- the hostname of the server, optionally with port: ``hostname.domain:port`` +- ``Share`` -- the share to connect to + +SMB/CIFS uses the password authentication scheme. See +:doc:`auth_mechanisms` for more information. + +Optionally, a ``Domain`` can be specified. This is useful in cases where the +SMB server requires a domain and a username, and an advanced authentication +mechanism like 'Session credentials' is used such that the username cannot be +modified. This is concatenated with the username, so the backend gets +``domain\username`` + +Optionally, a ``Remote subfolder`` can be specified to change the destination +directory within the share. The default is the root of the share. + +.. note:: For improved reliability and performance, it is recommended to + install ``libsmbclient-php``, a native PHP module for connecting to + SMB servers. It is available as ``php5-libsmbclient`` in the ownCloud + `OBS repositories `_ .. figure:: images/smb.png - -SMB/CIFS using OC login -------------------------- - -This works the same way as setting up a SMB/CIFS mount, except you can use your -ownCloud logins intead of the SMB/CIFS server logins. To make this work, your -ownCloud users need the same login and password as on the SMB/CIFS server. - -.. note:: Shares set up with ``SMB/CIFS using OC login`` cannot be shared in - ownCloud. If you need to share your SMB/CIFS mount, then use the SMB/CIFS - mount without oC login. diff --git a/admin_manual/configuration_files/external_storage/webdav.rst b/admin_manual/configuration_files/external_storage/webdav.rst index 9edc5a852..036a6e1a0 100644 --- a/admin_manual/configuration_files/external_storage/webdav.rst +++ b/admin_manual/configuration_files/external_storage/webdav.rst @@ -2,17 +2,20 @@ WebDAV ====== -Use these to mount a directory from any WebDAV server, or another +Use this backend to mount a directory from any WebDAV server, or another ownCloud server. -* Folder name -- Whatever name you want for your local mountpoint. -* URL -- The URL of the WebDAV or ownCloud server. -* Username and password for the remote server -* Remote Subfolder -- The remote subfolder you want to mount (optional, defaults - to ``/``) -* Secure ``https://`` - Whether to use ``https://`` to connect to the WebDav - server instead of ``http://`` (We always recommend ``https://`` for - security) +The following information is required: + +- ``URL`` -- The URL of the WebDAV or ownCloud server, including subdirectories + +WebDAV uses the password authentication scheme, see :doc:`auth_mechanisms` + +Optionally, a ``Remote Subfolder`` can be specified to change the desination +directory. The default is to use the whole root. + +The ``Secure https://`` checkbox can be used as an alternative to specifying +``https://`` in the ``URL`` field. .. figure:: images/webdav.png