Merge branch 'master' into document-files-transfer-ownership-in-10.4.1

koelle25 · Apr 15, 2020 · c10080d · c10080d
2 parents 0add10b + bc3d749
commit c10080d
Show file tree

Hide file tree

Showing 23 changed files with 209 additions and 55 deletions.
diff --git a/...min_manual/pages/configuration/files/federated_cloud_sharing_configuration.adoc b/...min_manual/pages/configuration/files/federated_cloud_sharing_configuration.adoc
@@ -12,7 +12,8 @@ When you enable the Federation app you can easily and securely link file shares
 For security reasons federated sharing **strictly requires HTTPS (SSL/TLS)**.
 ====
 
-NOTE: For testing purposes you can use `HTTP` but you have to set `'sharing.federation.allowHttpFallback' => true,` in your **config.php**.
+IMPORTANT: We strongly recommend using HTTP for development and testing purposes. 
+However, to do so, you have to set `'sharing.federation.allowHttpFallback' => true,` in **config/config.php**.
 
 == Configuration
 

diff --git a/...in_manual/pages/configuration/server/app_commands/password_policy_commands.adoc b/...in_manual/pages/configuration/server/app_commands/password_policy_commands.adoc
@@ -1,4 +1,5 @@
 = Password Policy
+:php-datetime-url: https://php.net/manual/datetime.formats.php
 
 Marketplace URL: https://marketplace.owncloud.com/apps/password_policy[Password Policy]
 

diff --git a/modules/admin_manual/pages/configuration/server/occ_command.adoc b/modules/admin_manual/pages/configuration/server/occ_command.adoc
@@ -2,7 +2,7 @@
 :toc: macro
 :toclevels: 2
 :page-aliases: configuration/server/occ_app_command.adoc,go/admin-cli-upgrade.adoc,configuration/files/external_storage_configuration.adoc
-:php-datetime-url: https://php.net/manual/de/datetime.formats.php
+:php-datetime-url: https://php.net/manual/datetime.formats.php
 :hsm-overview-url: https://www.cryptomathic.com/news-events/blog/understanding-hardware-security-modules-hsms
 :owncloud-support-url: https://owncloud.com/licenses/owncloud-support-maintenance/
 

diff --git a/modules/admin_manual/pages/configuration/server/occ_command/security_commands.adoc b/modules/admin_manual/pages/configuration/server/occ_command/security_commands.adoc
@@ -32,7 +32,7 @@ Example 1:
 +-----------------------------------------------------------+-----------------+
 | /apps/federation/auto-add-servers                         | POST            |
 | /apps/federation/trusted-servers                          | POST            |
-| /apps/federation/trusted-servers/{id}                     | DELETE          |
+| /apps/federation/trusted-servers/<id>                     | DELETE          |
 | /apps/files/                                              | GET             |
 | /apps/files/ajax/download.php                             |                 |
 ...

diff --git a/modules/admin_manual/pages/configuration/server/security/oauth2.adoc b/modules/admin_manual/pages/configuration/server/security/oauth2.adoc
@@ -1,13 +1,20 @@
 = OAuth2
 :toc: right
-:shibboleth-app-url: https://marketplace.owncloud.com/apps/user_shibboleth
+// Page URLs
+:mod_headers-url: http://httpd.apache.org/docs/current/mod/mod_headers.html
+:mod_rewrite-url: http://httpd.apache.org/docs/current/mod/mod_rewrite.html
 :oauth2-user-auth-url: https://oauth.net/articles/authentication/
+:phpredis-issue-url: https://github.com/owncloud/docs/issues/2491
+:predis-extension-session-locking-config-url: https://github.com/phpredis/phpredis/blob/develop/README.markdown#session-locking
+:predis-extension-url: https://github.com/phpredis/phpredis
+:shibboleth-app-url: https://marketplace.owncloud.com/apps/user_shibboleth
 
 == What is it?
 
 OAuth2 is summarized in https://tools.ietf.org/html/rfc6749#section-4.1.1[RFC 6749] as follows:
 
-  The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.
+[quote,OAuth2 Overview]
+The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.
 
 Here is an overview of how the process works:
 
@@ -49,6 +56,47 @@ The app aims to:
 . Connect ownCloud clients (both desktop and mobile) in a standardized and secure way.
 . Make 3rd party software integrations easier by providing an unified authorization interface.
 
+=== Requirements
+
+To use the OAuth2 app, your ownCloud installation will need to meet the following dependencies:
+
+* *Apache:* If you are hosting your ownCloud installation using the Apache web server, then {mod_rewrite-url}[mod_rewrite] and {mod_headers-url}[mod_headers] modules must be installed and enabled.
+. *Redis:* You will need to have a Redis server available, ideally the latest, stable, version
+. *PHP:* You PHP installation must have {predis-extension-url}[the phpredis extension] (>= 4.2) installed and enabled. 
++
+[TIP]
+====
+We strongly recommend that you configured PHP to store sessions in Redis.
+Here is an example configuration. 
+
+[source,ini]
+----
+; Redis configuration
+SESSION_SAVE_HANDLER=redis
+SESSION_SAVE_PATH=tcp://[REDIS_SERVER]:6397
+REDIS_SESSION_LOCKING_ENABLED=1
+REDIS_SESSION_LOCK_RETRIES=750
+REDIS_SESSION_LOCK_WAIT_TIME=20000
+----
+
+The configuration parameters above are taken from {predis-extension-session-locking-config-url}[the available ones].
+According to {phpredis-issue-url}[an issue in the phpredis repository], the default values are too small for common usage. 
+It suggested using the ones above instead.
+However, please adjust these values to meet your needs.
+====
+
+=== Installation
+
+To install the application, place the content of the OAuth2 app inside your installation's `app` directory, or use the Market application.
+
+=== Basic Configuration
+
+To enable token-only based app or client logins in `config/config.php` set `token_auth_enforced` to `true`.
+
+=== Restricting Usage
+
+- Enterprise installations can limit the access of authorized clients, preventing unwanted clients from connecting.
+
 === Endpoints
 
 [cols=",",options="header",]
@@ -157,26 +205,7 @@ For further information about client registration, please refer to https://tools
 NOTE: For a succinct explanation of the differences between access tokens and authorization codes, 
 check out https://stackoverflow.com/a/16341985/222011[this answer on StackOverflow].
 
-== Installation
-
-To install the application, place the content of the OAuth2 app inside your installation's `app` directory, or use the Market application.
-
-== Requirements
-
-If you are hosting your ownCloud installation from the Apache web server, then both the 
-http://httpd.apache.org/docs/current/mod/mod_rewrite.html[mod_rewrite] and
-http://httpd.apache.org/docs/current/mod/mod_headers.html[mod_headers] modules
-are required to be installed and enabled.
-
-== Basic Configuration
-
-To enable token-only based app or client logins in `config/config.php` set `token_auth_enforced` to `true`.
-
-== Restricting Usage
-
-- Enterprise installations can limit the access of authorized clients, preventing unwanted clients from connecting.
-
-== Limitations
+=== Limitations
 
 - Since the app does not handle user passwords, only master key encryption works (similar to {shibboleth-app-url}[the Shibboleth app]).
 - Clients cannot migrate accounts from Basic Authorization to OAuth2, if they are currently using the `user_ldap` backend.

diff --git a/modules/developer_manual/examples/core/webdav_api/meta/meta-files-filter.xml b/modules/developer_manual/examples/core/webdav_api/meta/meta-files-filter.xml
@@ -0,0 +1,7 @@
+<?xml version="1.0"?>
+<a:propfind xmlns:a="DAV:" xmlns:oc="http://owncloud.org/ns">
+    <a:prop>
+        <oc:meta-path-for-user/>
+    </a:prop>
+</a:propfind>
+
diff --git a/modules/developer_manual/examples/core/webdav_api/meta/report-propfind.xml b/modules/developer_manual/examples/core/webdav_api/meta/report-propfind.xml
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<a:propfind xmlns:a="DAV:" xmlns:oc="http://owncloud.org/ns">
+    <a:prop>
+        <oc:comments-unread />
+        <oc:display-name/>
+        <oc:favorites />
+        <oc:fileid />
+        <oc:owner-display-name />
+        <oc:permissions />
+        <oc:share-types />
+        <oc:size />
+        <oc:tags />
+        <oc:user-assignable/>
+        <oc:user-visible/>
+    </a:prop>
+</a:propfind>
diff --git a/modules/developer_manual/examples/core/webdav_api/meta/response-failure.xml b/modules/developer_manual/examples/core/webdav_api/meta/response-failure.xml
@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
+  <s:exception>Sabre\DAV\Exception\NotFound</s:exception>
+  <s:message/>
+</d:error>
diff --git a/modules/developer_manual/examples/core/webdav_api/meta/response-success.xml b/modules/developer_manual/examples/core/webdav_api/meta/response-success.xml
@@ -0,0 +1,12 @@
+<?xml version="1.0"?>
+<d:multistatus xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns" xmlns:oc="http://owncloud.org/ns">
+  <d:response>
+    <d:href>/remote.php/dav/meta/7/</d:href>
+    <d:propstat>
+      <d:prop>
+        <oc:meta-path-for-user>/Photos/San Francisco.jpg</oc:meta-path-for-user>
+      </d:prop>
+      <d:status>HTTP/1.1 200 OK</d:status>
+    </d:propstat>
+  </d:response>
+</d:multistatus>
diff --git a/modules/developer_manual/examples/scripts/backport.sh b/modules/developer_manual/examples/scripts/backport.sh
@@ -46,10 +46,10 @@ repository=$(git config --get remote.origin.url 2>/dev/null | perl -lne 'print $
 commitList=$(git log --no-merges --reverse --format=format:%h $1^..$1)
 
 # get the request reset time window from github in epoch
-rateLimitReset=$(curl -i https://api.github.com/users/octocat 2>&1 | grep -m1 'X-RateLimit-Reset:' | grep -o '[[:digit:]]*')
+rateLimitReset=$(curl -i https://api.github.com/users/octocat 2>&1 | grep -m1 'X-Ratelimit-Reset:' | grep -o '[[:digit:]]*')
 
 # get the remaining requests in window from github
-rateLimitRemaining=$(curl -i https://api.github.com/users/octocat 2>&1 | grep -m1 'X-RateLimit-Remaining:' | grep -o '[[:digit:]]*')
+rateLimitRemaining=$(curl -i https://api.github.com/users/octocat 2>&1 | grep -m1 'X-Ratelimit-Remaining:' | grep -o '[[:digit:]]*')
 
 # time remaining in epoch
 now=$(date +%s)

diff --git a/modules/developer_manual/nav.adoc b/modules/developer_manual/nav.adoc
@@ -35,6 +35,7 @@
 ***** xref:webdav_api/comments.adoc[The Comments API]
 ***** xref:webdav_api/groups.adoc[The Custom Groups Management API]
 ***** xref:webdav_api/files_versions.adoc[The Files Versions API]
+***** xref:webdav_api/meta.adoc[The Meta API]
 ***** xref:webdav_api/search.adoc[The Search API]
 ***** xref:webdav_api/tags.adoc[The Tags API]
 ***** xref:webdav_api/trashbin.adoc[The Trash Bin API]

diff --git a/modules/developer_manual/pages/_partials/webdav_api/search/file_properties.adoc b/modules/developer_manual/pages/_partials/webdav_api/search/file_properties.adoc
@@ -8,11 +8,10 @@
 |Description
 |Namespace
 
-a|[#file-property-getcontentlength]
-getcontentlength
+|getcontentlength
 |The file's content length.
 This is only sent for files, not for folders and collections.
-Refer to the xref:file-property-size[size] property for folders and collections.
+Refer to the `size` property for folders and collections.
 |`DAV`
 
 |getcontenttype
@@ -69,11 +68,10 @@ The share type values are:
 * `3`: link shares
 |`\http://owncloud.org/ns`
 
-a|[#file-property-size]
-size
+|size
 |The size of a folder or collection.
 This property is not returned for files.
-Refer to the xref:file-property-getcontentlength[getcontentlength] property for folders and collections.
+Refer to the `getcontentlength` property for folders and collections.
 |`\http://owncloud.org/ns`
 
 |tags

diff --git a/modules/developer_manual/pages/app/fundamentals/routes.adoc b/modules/developer_manual/pages/app/fundamentals/routes.adoc
@@ -187,10 +187,10 @@ $application = new Application();
 $application->registerRoutes($this, [
     'routes' => [
         ['name' => 'author#index', 'url' => '/authors', 'verb' => 'GET'],
-        ['name' => 'author#show', 'url' => '/authors/{id}', 'verb' => 'GET'],
+        ['name' => 'author#show', 'url' => '/authors/<id>', 'verb' => 'GET'],
         ['name' => 'author#create', 'url' => '/authors', 'verb' => 'POST'],
-        ['name' => 'author#update', 'url' => '/authors/{id}', 'verb' => 'PUT'],
-        ['name' => 'author#destroy', 'url' => '/authors/{id}', 'verb' => 'DELETE'],
+        ['name' => 'author#update', 'url' => '/authors/<id>', 'verb' => 'PUT'],
+        ['name' => 'author#destroy', 'url' => '/authors/<id>', 'verb' => 'DELETE'],
         // your other routes here
     ]
 ]);
@@ -284,7 +284,7 @@ class PageController extends Controller {
      */
     public function redirect() {
         // route name: author_api#do_something
-        // route url: /apps/news/myapp/authors/{id}
+        // route url: /apps/news/myapp/authors/<id>
 
         // # needs to be replaced with a . due to limitations and prefixed
         // with your app id

diff --git a/modules/developer_manual/pages/app/tutorial/routes_and_controllers.adoc b/modules/developer_manual/pages/app/tutorial/routes_and_controllers.adoc
@@ -49,10 +49,10 @@ return [
     'routes' => [
         ['name' => 'page#index', 'url' => '/', 'verb' => 'GET'],
         ['name' => 'note#index', 'url' => '/notes', 'verb' => 'GET'],
-        ['name' => 'note#show', 'url' => '/notes/{id}', 'verb' => 'GET'],
+        ['name' => 'note#show', 'url' => '/notes/<id>', 'verb' => 'GET'],
         ['name' => 'note#create', 'url' => '/notes', 'verb' => 'POST'],
-        ['name' => 'note#update', 'url' => '/notes/{id}', 'verb' => 'PUT'],
-        ['name' => 'note#destroy', 'url' => '/notes/{id}', 'verb' => 'DELETE']
+        ['name' => 'note#update', 'url' => '/notes/<id>', 'verb' => 'PUT'],
+        ['name' => 'note#destroy', 'url' => '/notes/<id>', 'verb' => 'DELETE']
     ]
 ];
 ----

diff --git a/modules/developer_manual/pages/core/apis/ocs-share-api.adoc b/modules/developer_manual/pages/core/apis/ocs-share-api.adoc
@@ -1130,9 +1130,8 @@ include::{examplesdir}core/scripts/responses/shares/update-share-success.xml[]
 
 == Federated Cloud Shares
 
-Both the sending and the receiving instance need to have federated cloud
-sharing enabled and configured. See
-xref:admin_manual:configuration/files/federated_cloud_sharing_configuration.adoc[Configuring Federated Cloud Sharing].
+Both the sending and the receiving instance need to have federated cloud sharing enabled and configured. 
+See xref:admin_manual:configuration/files/federated_cloud_sharing_configuration.adoc[Configuring Federated Cloud Sharing].
 
 === Create A New Federated Cloud Share
 

diff --git a/modules/developer_manual/pages/core/apis/ocs/notifications/ocs-endpoint-v1.adoc b/modules/developer_manual/pages/core/apis/ocs/notifications/ocs-endpoint-v1.adoc
@@ -109,11 +109,11 @@ This endpoint supports retrieving a list of notifications for a user.
 [TIP]
 ====
 In order to get a single notification, you can send a `GET` request against the endpoint below. 
-Note the {id} property at the end of the endpoint.
+Note the <id> property at the end of the endpoint.
 
 [source,console]
 ----
-{request-base-path}/apps/notifications/api/v1/notifications/{id}
+{request-base-path}/apps/notifications/api/v1/notifications/<id>
 ----
 ====
 
@@ -306,9 +306,9 @@ This status code means that there is no app that can generate notifications.
 
 == Delete a User Notification
 
-To delete a notification, send a `DELETE` request against `{request-base-path}/apps/notifications/api/v1/notifications/{id}`
+To delete a notification, send a `DELETE` request against `{request-base-path}/apps/notifications/api/v1/notifications/<id>`
 
-* Path: `{request-base-path}/apps/notifications/api/v1/notifications/{id}`
+* Path: `{request-base-path}/apps/notifications/api/v1/notifications/<id>`
 * Method: `DELETE`
 
 === Request Parameters

diff --git a/modules/developer_manual/pages/core/apis/ocs/user-sync-api.adoc b/modules/developer_manual/pages/core/apis/ocs/user-sync-api.adoc
@@ -7,7 +7,7 @@
 
 This endpoint triggers user-sync for a specific user.
 
-* Path: `{request-base-path}/cloud/user-sync/{userid}`
+* Path: `{request-base-path}/cloud/user-sync/<userid>`
 * Method: `POST`
 
 == Requirements

diff --git a/modules/developer_manual/pages/webdav_api/files_versions/list_files_versions.adoc b/modules/developer_manual/pages/webdav_api/files_versions/list_files_versions.adoc
@@ -3,7 +3,7 @@
 :toclevels: 1
 :content_type: text/xml
 :method: PROPFIND
-:request_path: remote.php/dav/meta/$fileid/v
+:request-base-path: remote.php/dav/meta/$fileid/v
 
 == Introduction
 

diff --git a/modules/developer_manual/pages/webdav_api/meta.adoc b/modules/developer_manual/pages/webdav_api/meta.adoc
@@ -0,0 +1,80 @@
+= Meta API
+:toc: right
+// Attributes for the core details include
+:request_path: remote.php/dav/meta/<fileid> 
+:method: PROPFIND
+:content_type: text/xml
+:report-request-uri: https://tools.ietf.org/html/rfc3253#section-3.6
+:libxml-url: http://www.xmlsoft.org
+:http207-url: https://httpstatuses.com/207
+:http404-url: https://httpstatuses.com/404
+
+
+== Introduction
+
+An authenticated `PROPFIND` request to `{request_path}` returns the path to a file/folder for the logged in user.
+
+TIP: To retrieve a list of available files, use xref:webdav_api/search.adoc#limiting-returned-file-properties[the Filter Files endpoint], and ensure that returned properties includes `fileid`. 
+
+include::{partialsdir}/webdav_api/core_request_details.adoc[leveloffset=+1]
+
+== Request Parameters
+
+[cols=",,",options="header",]
+|===
+|Attribute 
+|Type 
+|Description
+
+|`fileid` 
+|integer 
+|The file's id.
+|===
+
+TIP: The example above uses xmllint, available in {libxml-url}[the libxml2 package] to make the response easier to read.
+
+== Example Responses
+
+=== Success
+
+If the file of folder is found, then a response similar to the following will be returned with an {http207-url}[HTTP/1.1 207 Multi-Status] status:
+
+[source,xml]
+----
+include::{examplesdir}/core/webdav_api/meta/response-success.xml[]
+----
+
+=== Failure
+
+If the file is not found, then the following response will be returned with an {http404-url}[HTTP/1.1 404 Not Found] status:
+
+[source,xml]
+----
+include::{examplesdir}/core/webdav_api/meta/response-failure.xml[]
+----
+
+== Example Request
+
+[tabs]
+====
+Curl::
++
+--
+[source,console,subs="attributes+"]
+----
+curl -u {oc-examples-username}:{oc-examples-password} \
+  -X PROPFIND \
+  -H "Depth: 0" \
+  -H "Content-Type: text/xml" \
+  --data "@meta-files.xml" \
+  '{oc-examples-server-url}/remote.php/dav/meta/<fileid>' | xmllint --format -
+----
+--
+====
+
+=== meta-files.xml
+
+[source,xml]
+----
+include::{examplesdir}core/webdav_api/meta/meta-files-filter.xml[]
+----