mirrors/nextcloud-documentation
3
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2025-10-26 11:18:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

ldap default password policy

Browse Source 
Signed-off-by: Roger Szabo <roger.szabo@web.de>
This commit is contained in:
Roger Szabo 2017-04-25 17:25:59 +08:00
commit c0bfba2fcc
324 changed files with 5516 additions and 1631 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
.drone.yml
View File

@ -1,6 +1,8 @@
build:
image: nextcloudci/documentation:1.0.11
commands:
- (cd user_manual && make html-all)
- (cd admin_manual && make html-all)
- (cd developer_manual && make html-all)
pipeline:
documentation:
image: nextcloudci/documentation:1.0.11
commands:
- (cd user_manual && make html-all)
- (cd admin_manual && make html-all)
- (cd developer_manual && make html-all)
- (cd user_manual_de && make html-all)

13
Makefile
View File

@ -1,7 +1,7 @@
all: html pdf
html: admin-manual-html user-manual-html developer-manual-html
pdf: admin-manual-pdf user-manual-pdf developer-manual-pdf
html: admin-manual-html user-manual-html user-manual-de-html developer-manual-html
pdf: admin-manual-pdf user-manual-pdf user-manual-de-pdf developer-manual-pdf
admin-manual-html:
rm -rf admin_manual/_build/html/com
@ -13,6 +13,11 @@ user-manual-html:
cd user_manual && make html
@echo "User manual build finished; HTML is updated"
user-manual-de-html:
rm -rf user_manual_de/_build/html/com
cd user_manual_de && make html
@echo "User manual de build finished; HTML is updated"
developer-manual-html:
rm -rf developer_manual/_build/html/com
cd developer_manual && make html
@ -26,6 +31,10 @@ user-manual-pdf:
cd user_manual && make latexpdf
@echo "User manual build finished; PDF is updated"
user-manual-de-pdf:
cd user_manual_de && make latexpdf
@echo "User manual de build finished; PDF is updated"
developer-manual-pdf:
cd developer_manual && make latexpdf
@echo "Developer manual build finished; PDF is updated"

40
README.rst
View File

@ -2,10 +2,10 @@
Nextcloud Documentation
=======================
Documentation is published on `<https://docs.nextcloud.org>`_.
Documentation is published on `<https://docs.nextcloud.com>`_.
The `documentation Wiki <https://github.com/nextcloud/documentation/wiki>`_ is
available for tips, tricks, edge cases, and anyone who wants to contribute more
The `documentation Wiki <https://github.com/nextcloud/documentation/wiki>`_ is
available for tips, tricks, edge cases, and anyone who wants to contribute more
easily, without having to learn Git and Sphinx.
See the `Style Guide <https://github.com/nextcloud/documentation/blob/master/style_guide.rst>`_ for formatting and style conventions.
@ -17,9 +17,9 @@ This repository hosts four manuals:
* **Users' Manual**
* **Administration Manual**
* **Developers Manual**
Please work in the appropriate branch. Stable8 is 8.0, stable8.1 is 8.1, stable8.2 is 8.2, stable9 is 9.0, and master is version 9.1.
* **Developers Manual**
Please work in the appropriate branch: ``stable9`` is 9.0, ``stable10`` is 10.0, ``stable11`` is 11.0 and ``master`` is version 12.0.
Please wrap lines at 80 characters.
@ -31,7 +31,7 @@ Spelling and Capitalization Conventions
As this grows it may be moved to its own page.
* Nextcloud Apps Store
* Nextcloud App Store
* synchronize
* Web (Web page, Web site)
@ -54,24 +54,24 @@ from GitHub.
Editing
-------
Contributing to the documentation requires a Github account. Make sure you are
working in the correct branch for your version of Nextcloud or client apps.
If your edits pertain to multiple manual versions, be prepared to backport as
Contributing to the documentation requires a Github account. Make sure you are
working in the correct branch for your version of Nextcloud or client apps.
If your edits pertain to multiple manual versions, be prepared to backport as
needed.
To edit a document, you can edit the .rst files on your local system, or work
directly on Github. The latter is only suitable for small fixes and improvements
because substantial editing efforts can better be controlled on your local PC.
To edit a document, you can edit the .rst files on your local system, or work
directly on Github. The latter is only suitable for small fixes and improvements
because substantial editing efforts can better be controlled on your local PC.
The best way is to install a complete Sphinx build environment and work on your
local PC. You will be able to make your own local builds, which is the fastest
and best way to preview for errors. Sphinx will report syntax errors, missing
images, and formatting errors. The Github preview is not complete and misses
many mistakes. Create a new branch against the master or stable branch you are
editing, make your edits, then push your new branch to Github and open a new PR.
The best way is to install a complete Sphinx build environment and work on your
local PC. You will be able to make your own local builds, which is the fastest
and best way to preview for errors. Sphinx will report syntax errors, missing
images, and formatting errors. The Github preview is not complete and misses
many mistakes. Create a new branch against the master or stable branch you are
editing, make your edits, then push your new branch to Github and open a new PR.
To edit on Github, fork the repository (see top-right of the screen, under
your username). You will then be able to make changes easily. Once done,
your username). You will then be able to make changes easily. Once done,
you can create a pull request and get the changes reviewed and back into
the official repository.

54
_shared_assets/themes/nextcloud_com/static/styles.css
View File

@ -68,6 +68,10 @@ h3 {
margin: 12px 0;
}
img {
max-width: 100%;
}
.btn {
border-radius: 50px;
}
@ -1077,3 +1081,53 @@ h4:hover a.headerlink {
a.headerlink {
display: none;
}
#menu-support {
padding-left: 0;
color: #428bca;
}
#menu-support > ul {
padding-left: 0;
list-style-type: none;
}
#menu-support > ul > li {
padding: 5px 9px;
padding-right: 0;
}
#menu-support > ul > li:nth-child(odd) {
border-top: 1px solid #ccc;
border-bottom: 1px solid #ccc;
}
#menu-support > ul > li:last-child {
border-bottom: 0;
}
#menu-support > ul > .current {
border: 1px solid #999 !important;
border-right: 0 !important;
border-bottom-left-radius: 5px;
border-top-left-radius: 5px;
}
#menu-support > ul > .current + li{
border-top: 0;
}
#menu-support ul ul {
padding-left: 27px;
}
/* round bullets for the second level entries */
#menu-support.menu ul ul {
list-style-type: disc;
}
/* square bullets for the third level entries */
#menu-support.menu ul ul ul {
list-style-type: square;
}
/* having a separator between each elements of the top list and
between above the top of the third level list */
#menu-support.menu ul ul ul {
border-top: 1px solid #EFEFEF;
}

50
_shared_assets/themes/nextcloud_release/static/styles.css
View File

@ -314,12 +314,6 @@ ul#menu-support.menu > ul > li,
ul#menu-support.menu ul ul ul {
border-top: 1px solid #EFEFEF;
}
/* highlight the current list entry of the first list with white
font on blue background */
ul#menu-support.menu > ul > li.current {
background-color: #428BCA;
color: white;
}
/* set to default padding for the sublist of the current entry */
ul#menu-support.menu ul > li.current > ul {
padding-left: 20px;
@ -339,19 +333,41 @@ ul#menu-support.menu > ul li.toctree-l1 {
ul#menu-support.menu > ul li.toctree-l1.current {
padding-bottom: 10px;
}
/* override the color of links */
ul#menu-support.menu ul > li.current > a:hover,
ul#menu-support.menu ul > li.current > a:focus,
ul#menu-support.menu ul > li.current > a {
color: white;
#menu-support {
padding-left: 0;
}
/* override the color of the current link */
ul#menu-support.menu ul > li.current > a.current {
color: #428BCA;
#menu-support > ul {
padding-left: 0;
list-style-type: none;
}
/* override the color of the current link in the first level */
ul#menu-support.menu > ul > li.current > a.current {
color: white;
#menu-support > ul > li {
padding: 5px 9px;
padding-right: 0;
}
#menu-support > ul > li:nth-child(odd) {
border-top: 1px solid #ccc;
border-bottom: 1px solid #ccc;
}
#menu-support > ul > li:last-child {
border-bottom: 0;
}
#menu-support > ul > .current {
border: 1px solid #999 !important;
border-right: 0 !important;
border-bottom-left-radius: 5px;
border-top-left-radius: 5px;
}
#menu-support > ul > .current + li{
border-top: 0;
}
#menu-support ul ul {
padding-left: 27px;
}
.headerlink {

26
admin_manual/conf.py
View File

@ -44,13 +44,13 @@ master_doc = 'contents'
# built documents.
#
# The short X.Y version.
version = '9.1'
version = '11'
# The full version, including alpha/beta/rc tags.
release = '9.1'
release = '11 alpha'
# General information about the project.
project = u'ownCloud %s Server Administration Manual' % (version)
copyright = u'2012-2016, The ownCloud developers'
project = u'Nextcloud %s Server Administration Manual' % (version)
copyright = u'2012-2016, The Nextcloud developers'
# The language for content autogenerated by Sphinx. Refer to documentation
@ -166,7 +166,7 @@ html_show_sphinx = False
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'ownCloudServerAdminManual'
htmlhelp_basename = 'NextcloudServerAdminManual'
# -- Options for LaTeX output --------------------------------------------------
@ -185,7 +185,7 @@ latex_elements = {'preamble': '\usepackage{morefloats}', 'figure_align': 'H',
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [('contents', 'ownCloud_Server_Administration_Manual.tex', u'ownCloud Server Administration Manual', u'The ownCloud developers', 'manual'),]
latex_documents = [('contents', 'Nextcloud_Server_Administration_Manual.tex', u'Nextcloud Server Administration Manual', u'The Nextcloud developers', 'manual'),]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
@ -209,13 +209,13 @@ latex_logo = '../_shared_assets/static/logo-blue.pdf'
# -- Options for pdf page output -----------------------------------------------
pdf_documents = [('contents', u'owncloud Server Administration Manual', u'ownCloud Server Administration Manual', u'The ownCloud developers'),]
pdf_documents = [('contents', u'Nextcloud Server Administration Manual', u'Nextcloud Server Administration Manual', u'The Nextcloud developers'),]
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [ ('contents', 'owncloudserveradminmanual', u'ownCloud Server Administration Manual', [u'The ownCloud developers'], 1) ]
man_pages = [ ('contents', 'nextcloudserveradminmanual', u'Nextcloud Server Administration Manual', [u'The Nextcloud developers'], 1) ]
# If true, show URL addresses after external links.
#man_show_urls = False
@ -226,7 +226,7 @@ man_pages = [ ('contents', 'owncloudserveradminmanual', u'ownCloud Server Admini
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [ ('contents', 'ownCloud Server Admin Manual', u'ownCloud Server Administration Manual', u'The ownCloud developers', 'ownCloud', 'The ownCloud Server Administration Manual.', 'Miscellaneous'), ]
texinfo_documents = [ ('contents', 'Nextcloud Server Admin Manual', u'Nextcloud Server Administration Manual', u'The Nextcloud developers', 'Nextcloud', 'The Nextcloud Server Administration Manual.', 'Miscellaneous'), ]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
@ -241,10 +241,10 @@ texinfo_documents = [ ('contents', 'ownCloud Server Admin Manual', u'ownCloud Se
# -- Options for Epub output ---------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = u'ownCloud Server Administration Manual'
epub_author = u'The ownCloud developers'
epub_publisher = u'The ownCloud developers'
epub_copyright = u'2012-2016, The ownCloud developers'
epub_title = u'Nextcloud Server Administration Manual'
epub_author = u'The Nextcloud developers'
epub_publisher = u'The Nextcloud developers'
epub_copyright = u'2012-2016, The Nextcloud developers'
# The language of the text. It defaults to the language option
# or en if the language is not set.

2
admin_manual/configuration_database/linux_database_configuration.rst
View File

@ -175,7 +175,7 @@ You can quit the prompt by entering::
\q
An Nextcloud instance configured with PostgreSQL would contain the path to the socket on
which the database is running as the hostname, the system username the php process is using,
which the database is running as the hostname, the system username the PHP process is using,
and an empty password to access it, and the name of the database. The :file:`config/config.php` as
created by the :doc:`../installation/installation_wizard` would therefore contain entries like
this:

16
admin_manual/configuration_files/big_file_upload_configuration.rst
View File

@ -21,7 +21,7 @@ filesystem.
System Configuration
--------------------
* Make sure that the latest version of PHP (at least 5.4.9) is installed
* Make sure that the latest version of PHP (at least 5.6.6) is installed
* Disable user quotas, which makes them unlimited
* Your temp file or partition has to be big enough to hold multiple
parallel uploads from multiple users; e.g. if the max upload size is 10GB and
@ -75,12 +75,18 @@ Apache with mod_fcgid
Setting ``FcgidMaxRequestInMem`` significantly higher than normal may no longer be
necessary, once bug #51747 is fixed.
NGINX
nginx
^^^^^
* `client_max_body_size <http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size>`_
* `fastcgi_read_timeout <http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_read_timeout>`_
* `client_body_temp_path <http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_temp_path>`_
Since nginx 1.7.11 a new config option `fastcgi_request_buffering
<https://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_request_buffering`_
is availabe. Setting this option to ``fastcgi_request_buffering off;`` in your nginx config
might help with timeouts during the upload. Furthermore it helps if you're running out of
disc space on the tmp partition of your system.
For more info how to configure nginx to raise the upload limits see also `this
<https://github.com/owncloud/documentation/wiki/Uploading-files-up-to-16GB#configuring-nginx>`_
wiki entry.
@ -91,7 +97,7 @@ wiki entry.
performance, place these on a separate hard drive that is dedicated to
swap and temp storage.
If your site is behind a Nginx frontend (for example a loadbalancer):
If your site is behind a nginx frontend (for example a loadbalancer):
By default, downloads will be limited to 1GB due to ``proxy_buffering`` and ``proxy_max_temp_file_size`` on the frontend.
@ -114,7 +120,7 @@ file size values::
upload_max_filesize = 16G
post_max_size = 16G
Tell PHP which temp file you want it to use::
Tell PHP which temp directory you want it to use::
upload_tmp_dir = /var/big_temp_file/
@ -153,7 +159,7 @@ this input box.
To be able to use this input box you need to make sure that:
* your Web server is be able to use the ``.htaccess`` file shipped by Nextcloud (Apache only)
* your Web server is able to use the ``.htaccess`` file shipped by Nextcloud (Apache only)
* the user your Web server is running as has write permissions to the files ``.htaccess`` and ``.user.ini``
:ref:`strong_perms_label` might prevent write access to these files. As an admin you need

51
admin_manual/configuration_files/collaborative_documents_configuration.rst
View File

@ -1,51 +0,0 @@
Configuring the Collaborative Documents App
===========================================
The Documents application supports editing documents within Nextcloud, without the
need to launch an external application. The Documents app supports these
features:
* Cooperative edit, with multiple users editing files simultaneously.
* Document creation within Nextcloud.
* Document upload.
* Share and edit files in the browser, and then share them inside Nextcloud or
through a public link.
Supported file formats are `.odt`, `.doc`, and `.docx`. `.odt` is supported
natively in Nextcloud, and you must have LibreOffice or OpenOffice installed on
the Nextcloud server to convert `.doc`, and `.docx` documents.
Enabling the Documents App
--------------------------
Go to your Apps page and click the ``Enable`` button. You also have the option
to grant access to the Documents apps to selected user groups. By default it is
available to all groups.
.. image:: ../images/documents_app_enable.png
See "Collaborative Document Editing" in the User manual to learn how to create
and share documents in the Documents application.
Enabling and testing MS Word support
------------------------------------
Go to your admin settings menu. After choosing ``Local`` or ``External`` click
on the ``Apply and test`` button. If you have a working LibreOffice or OpenOffice
installation a green ``Saved`` icon should appear.
.. image:: ../images/documents_apply_test.png
Troubleshooting
~~~~~~~~~~~~~~~
If the mentioned test fails please make sure that:
* the PHP functions ``escapeshellarg`` and ``shell_exec`` are not disabled in your
PHP configuration
* the libreoffice/openoffice binary is within your PATH and is executeable for the
HTTP user
* your SELinux configuration is not blocking the execution of the binary
* the PHP ``open_basedir`` is correctly configured to allow the access to the binary
More hints why the test is failing can be found in your ``data/nextcloud.log``.

4
admin_manual/configuration_files/encryption_configuration.rst
View File

@ -143,6 +143,8 @@ Encryption settings can be configured in the mount options for an external
storage mount, see :ref:`external_storage_mount_options_label`
(:doc:`external_storage_configuration_gui`)
.. _enable-file-recovery-key:
Enabling Users File Recovery Keys
----------------------------------
@ -214,7 +216,7 @@ command gives you the option to encrypt all files. You must first put your
Nextcloud server into single-user mode to prevent any user activity until
encryption is completed::
occ maintenance:singleuser
occ maintenance:singleuser --on
Single user mode is currently enabled
Then run ``occ``::

39
admin_manual/configuration_files/external_storage/auth_mechanisms.rst
View File

@ -2,12 +2,16 @@
External Storage Authentication mechanisms
==========================================
Nextcloud storage backends accept one or more authentication schemes such as
passwords, OAuth, or token-based, to name a few examples. Each authentication
scheme may be implemented by multiple authentication mechanisms. Different
mechanisms require different configuration parameters, depending on their
Nextcloud storage backends accept one or more authentication schemes such as
passwords, OAuth, or token-based, to name a few examples. Each authentication
scheme may be implemented by multiple authentication mechanisms. Different
mechanisms require different configuration parameters, depending on their
behaviour.
.. figure:: images/authentication-types.png
:alt: Authentication types
Special Mechanisms
------------------
@ -23,15 +27,30 @@ Password-based Mechanisms
-------------------------
The **Username and password** mechanism requires a manually-defined username and
password. These get passed directly to the backend.
password. These get passed directly to the backend and are specified during the
setup of the mount point.
The **Log-in credentials, save in session** mechanism uses the Nextcloud login
credentials of the user to connect to the storage. These are not stored anywhere
on the server, but rather in the user session, giving increased security. The
drawbacks are that sharing is disabled when this mechanism is in use, as
Nextcloud has no access to the storage credentials, and background file scanning
The **Log-in credentials, save in session** mechanism uses the Nextcloud login
credentials of the user to connect to the storage. These are not stored anywhere
on the server, but rather in the user session, giving increased security. The
drawbacks are that sharing is disabled when this mechanism is in use, as
Nextcloud has no access to the storage credentials, and background file scanning
does not work.
The **Log-in credentials, save in database** mechanism uses the Nextcloud login
credentials of the user to connect to the storage. These are stored in the
database encrypted with the shared secret. This allows to share files from
within this mount point.
The **User entered, store in database** mechanism work in the same way as the
"Username and password" mechanism but the credentials need to be specified by
each user individually. Before the first access to that mount point the user
will be prompted to enter the credentials.
The **Global credentials** mechanism uses the general input field for "Global
credentials" in the external storage settings section as source for the
credentials instead of individual credentials for a mount point.
Public-key Mechanisms
---------------------

8
admin_manual/configuration_files/external_storage/google.rst
View File

@ -69,8 +69,10 @@ then enter your app name. **Authorized JavaScript Origins** is your root domain,
for example ``https://example.com``, without a trailing slash. You need two
**Authorized Redirect URIs**, and they must be in this form::
https://example.com/nextcloud/index.php/settings/personal
https://example.com/nextcloud/index.php/settings/admin
https://example.com/nextcloud/index.php/settings/personal/
https://example.com/nextcloud/index.php/personal/
https://example.com/nextcloud/index.php/settings/admin/externalstorages
https://example.com/nextcloud/settings/admin/externalstorages
Replace ``https://example.com/nextcloud/`` with your own Nextcloud server URL,
then click **Create**.
@ -110,4 +112,4 @@ See :doc:`../external_storage_configuration_gui` for additional mount
options and information.
See :doc:`auth_mechanisms` for more information on authentication schemes.
603026686136-qnv9ooocacrkrh1vs0cht83eprgm2sbb.apps.googleusercontent.com
603026686136-qnv9ooocacrkrh1vs0cht83eprgm2sbb.apps.googleusercontent.com

BIN
admin_manual/configuration_files/external_storage/images/authentication-types.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 67 KiB

32
admin_manual/configuration_files/external_storage/smb.rst
View File

@ -45,3 +45,35 @@ See :doc:`../external_storage_configuration_gui` for additional mount
options and information.
See :doc:`auth_mechanisms` for more information on authentication schemes.
------------------------
SMB update notifications
------------------------
Starting with Nextcloud 10, Nextcloud can use smb update notifications to
listen to changes made to a configured SMB/CIFS storage and detect external
changes made to the storage in near real-time.
.. note:: Due to limitations of linux based SMB servers, this feature only works
reliably on Windows SMB servers.
.. note:: Using update notifications requires ``smbclient`` 4.x or newer.
Due to limitations with the smbclient PHP module, the ``smbclient`` binary
is required even when using the PHP module.
To start listening to update notifications, start the ``occ`` command like this::
occ files_external:notify <mount_id>
You can find the mount id for a specific storage using ``occ files_external:list``
On default this command shows no output, can you see the list of detected changes by
passing the ``-v`` option to the command.
~~~~~~~~~~~~~~~~~~
SMB Authentication
~~~~~~~~~~~~~~~~~~
In some cases (such as when using login credentials) it's not possible to read the
smb credentials from the storage configuration, in those cases you can provide
the username and password using the ``--username`` and ``--password`` arguments.

112
admin_manual/configuration_files/files_access_control.rst Normal file
View File

@ -0,0 +1,112 @@
====================
Files Access Control
====================
Nextcloud's File Access Control app enables administrators to create and
manage a set of rule groups. Each of the rule groups consists of one or more
rules. If all rules of a group hold true, the group matches the request and
access is being denied. The rules criteria range from IP address, to user
groups, collaborative tags and :ref:`some more <available-rules-label>`.
Denied access
-------------
If access to a file has been denied for a user, the user can not:
* Create/upload the file
* Modify the files
* Delete the file
* Download the file
* Syncronise the file with clients, such as the Nextcloud desktop and mobile clients
Examples
--------
.. figure:: images/files_access_control_sample_rules.png
:alt: Sample rules to block on user group, time and IP base.
The first rule group ``Support only 9-5`` denies any access to files for users
of the Support user group, between 5pm and 9am.
The second rule group ``Internal testing`` prevents users of the Internal
testers group to access files from outside of the local network.
Denying access to folders
-------------------------
The easiest way to block access to a folder, is to use a collaborative tag. As
mentioned in the :ref:`Available rules <available-rules-label>` section below,
either the file itself or one of the parents needs to have the given tag
assigned.
So you just need to assign the tag to the folder or file, and then block the
tag with a rule group. The check is independent of the user's permissions for
the tag. Therefor restricted and invisible tags are recommended, otherwise a
user could remove and reassign the tag.
This example blocks access to any folder with the tag ``Confidential``.
.. figure:: images/files_access_control_collaborative_tags.png
:alt: Deny access based on collaborative tag
Prevent uploading of specific files
-----------------------------------
It's possible to prevent specific files from being uploaded to Nextcloud. You
simply need to define a rule based on the mimetype and our powerful access control
engine will block any attempt to upload the file. The safest way to define the rule
is to use a regular expression, as it will help you cover all the known media types
used for the type of file you're trying to block.
The following example prevents zip files from being uploaded by using the regular
expression: ``/^application\/(zip|x-zip-compressed)$/i``
.. figure:: images/files_access_control_block_mimetype.png
:alt: Prevent upload based on mimetype
Common misconfigurations
------------------------
Blocking user groups
====================
When trying to deny access to a group of users, make sure that sharing does not
allow them to create a way back in. When users are able to create a public link,
the users can log themselves out and visit their own public link to access the
files. Since at this point they are no user and therefor no member of the
blocked group, they will be able to read and change the file.
The recommended work around is to create the same rule again, and deny access
for all users that are ``not member of`` a group, that contains all users of
your installation.
External storage
================
While access to files in external storages is not possible via Nextcloud, users
that have direct access to the external storage, can of course change files
there directly. Therefor it is recommended to disable the ``Allow users to mount
external storage`` option, when trying to to completely lock out users.
.. _available-rules-label:
Available rules
---------------
All rules can also be inverted (from ``is`` to ``is not``) using the operator
option.
* **File collaborative tag:** Either the file itself, or any of the file
owner's parent folders needs to be tagged with the tag.
* **File mimetype:** The mimetype of the file, e.g. ``text/plain``
* **File size:** The size of the file (*Only available on upload*)
* **Request remote address:** An IP range (either v4 or v6) for the accessing user
* **Request time:** Time span and timezone when the request happens
* **Request URL:** The URL which requests the file. (*This is the URL the file
is served from, not the URL the user is currently looking at.*)
* **Request user agent:** The user agent of the users browser or client.
Nextcloud desktop, Android and iOS clients are available as preconfigured
options.
* **User group membership:** Whether the user is a member of the given group.

62
admin_manual/configuration_files/files_locking_transactional.rst
View File

@ -2,42 +2,34 @@
Transactional File Locking
==========================
Nextcloud's Transactional File Locking mechanism locks files to avoid
Nextcloud's Transactional File Locking mechanism locks files to avoid
file corruption during normal operation. It performs these functions:
* Operates at a higher level than the filesystem, so you don't need to use a
* Operates at a higher level than the filesystem, so you don't need to use a
filesystem that supports locking
* Locks parent directories so they cannot be renamed during any activity on
* Locks parent directories so they cannot be renamed during any activity on
files inside the directories
* Releases locks after file transactions are interrupted, for
* Releases locks after file transactions are interrupted, for
example when a sync client loses the connection during an upload
* Manages locking and releasing locks correctly on shared files during changes
* Manages locking and releasing locks correctly on shared files during changes
from multiple users
* Manages locks correctly on external storage mounts
* Manages encrypted files correctly
What Transactional File locking is not for: it is not for preventing collisions
in collaborative document editing (see
:doc:`collaborative_documents_configuration` to learn about collaboration with
the Documents app), nor will it prevent multiple users from editing the same
document, or give notice that other users are working on the same document.
Multiple users can open and edit a file at the same time and Transactional File
locking does not prevent this. Rather, it prevents simultaneous file saving.
What Transactional File locking is not for: it will not prevent multiple users
from editing the same document, or give notice that other users are working on
the same document. Multiple users can open and edit a file at the same time and
Transactional File locking does not prevent this. Rather, it prevents
simultaneous file saving.
.. note:: Transactional file locking is in Nextcloud core, and replaces the old
File Locking app. The File Locking app has been removed from Nextcloud in
version 8.2.1. If your Nextcloud server still has the File Locking app, you
must visit your Apps page to verify that it is disabled; the File Locking
app and Transactional File Locking cannot both operate at the same time.
File locking is enabled by default, using the database locking backend. This
places a significant load on your database. Using ``memcache.locking`` relieves
the database load and improves performance. Admins of Nextcloud servers with
heavy workloads should install a memcache. (See
:doc:`../configuration_server/caching_configuration`.)
File locking is enabled by default, using the database locking backend. This
places a significant load on your database. Using ``memcache.locking`` relieves
the database load and improves performance. Admins of Nextcloud servers with
heavy workloads should install a memcache. (See
:doc:`../configuration_server/caching_configuration`.)
To use a memcache with Transactional File Locking, you must install the Redis
server and corresponding PHP module. After installing Redis you must enter a
To use a memcache with Transactional File Locking, you must install the Redis
server and corresponding PHP module. After installing Redis you must enter a
configuration in your ``config.php`` file like this example::
'filelocking.enabled' => true,
@ -63,20 +55,20 @@ recommended if Redis is running on the same system as Nextcloud) use this exampl
'port' => 0,
'timeout' => 0.0,
),
See ``config.sample.php`` to see configuration examples for Redis, and for all
See ``config.sample.php`` to see configuration examples for Redis, and for all
supported memcaches.
If you are on Ubuntu you can follow `this guide
<https://www.techandme.se/how-to-configure-redis-cache-in-ubuntu-14-04-with-owncloud/>`_ for a complete installation from scratch.
If you are on Ubuntu you can follow `this guide
<https://www.techandme.se/how-to-configure-redis-cache-in-ubuntu-14-04-with-owncloud/>`_ for a complete installation from scratch.
Learn more about Reds at `Redis <http://redis.io/>`_. Memcached, the popular
distributed memory caching system, is not suitable for the new file locking
because it is not designed to store locks, and data can disappear from the cache
at any time. Redis is a key-value store, and it guarantees that cached objects
Learn more about Reds at `Redis <http://redis.io/>`_. Memcached, the popular
distributed memory caching system, is not suitable for the new file locking
because it is not designed to store locks, and data can disappear from the cache
at any time. Redis is a key-value store, and it guarantees that cached objects
are available for as long as they are needed.
Debian Jesse users, please see this `Github discussion
<https://github.com/owncloud/core/issues/20675>`_ if you have problems with
Debian Jesse users, please see this `Github discussion
<https://github.com/owncloud/core/issues/20675>`_ if you have problems with
LDAP authentication.

BIN
admin_manual/configuration_files/images/files_access_control_block_mimetype.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
admin_manual/configuration_files/images/files_access_control_collaborative_tags.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
admin_manual/configuration_files/images/files_access_control_sample_rules.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 35 KiB

3
admin_manual/configuration_files/index.rst
View File

@ -9,12 +9,13 @@ File Sharing and Management
file_sharing_configuration
federated_cloud_sharing_configuration
big_file_upload_configuration
collaborative_documents_configuration
default_files_configuration
external_storage_configuration_gui
external_storage_configuration
external_storage/auth_mechanisms
primary_storage
encryption_configuration
files_locking_transactional
previews_configuration
file_versioning
files_access_control

132
admin_manual/configuration_files/primary_storage.rst Normal file
View File

@ -0,0 +1,132 @@
===========================
Primary Storage
===========================
It's possible to use an object store as primary storage, this replaces the default
way of storing files in :code:`nextcloud/data` (note that the data directory might still be used
for other reasons)
---------------------------
Implications
---------------------------
When using an object store as primary storage, Nextcloud assumes exclusive access
over the bucket being used.
Contrary to using an object store as external storage, when an object store is used
as primary storage, no metadata (names, directory structures, etc) is stored in the
object store. The metadata is only stored in the database and the object store only
holds the file content by unique identifier.
Because of this primary object stores usually perform better than when using the same
object store as external storage but it restricts being able to access the files from
outside of Nextcloud.
---------------------------
Configuring
---------------------------
Primary object stores need to be configured in :code:`config.php` by specifying the objectstore
backend and any backend specific configuration.
.. note:: Configuring a primary object store on an existing Nextcloud instance will
make all existing files on the instance inaccessible.
The configuration has the following structure.
::
'objectstore' => array(
'class' => 'Object\\Storage\\Backend\\Class',
'arguments' => array(
...
),
),
~~~~~~~~~~~~~~~
Openstack Swift
~~~~~~~~~~~~~~~
The Swift backend mounts a container on an OpenStack Object Storage server into the virtual filesystem. The class to be used is :code:`\\OC\\Files\\ObjectStore\\Swift`
::
'objectstore' => array(
'class' => 'OC\\Files\\ObjectStore\\Swift',
'arguments' => array(
'username' => 'username',
'password' => 'Secr3tPaSSWoRdt7',
// the container to store the data in
'bucket' => 'nextcloud',
'autocreate' => true,
'region' => 'RegionOne',
// The Identity / Keystone endpoint
'url' => 'http://example.com/v2.0',
// optional on some swift implementations
'tenantName' => 'username',
'serviceName' => 'swift',
// The Interface / url Type, optional
'urlType' => 'internal'
),
),
---------
Amazon S3
---------
The S3 backend mounts a bucket on an Amazon S3 Storage or compatible server into the virtual filesystem. The class to be used is :code:`\\OC\\Files\\ObjectStore\\S3`
::
'objectstore' => array(
'class' => 'OC\\Files\\ObjectStore\\S3',
'arguments' => array(
'bucket' => 'nextcloud',
'autocreate' => true,
'key' => 'EJ39ITYZEUH5BGWDRUFY',
'secret' => 'M5MrXTRjkyMaxXPe2FRXMTfTfbKEnZCu+7uRTVSj',
'hostname' => 'example.com',
'port' => 1234,
'use_ssl' => true,
'region' => 'optional',
// required for some non amazon s3 implementations
'use_path_style'=>true
),
),
Not all configuration options are required for all S3 servers.
Overriding the hostname, port and region of your S3 server is only
required for non-Amazon servers such as Ceph Object Gateway, which in turn
usually don't require the region to be set.
:code:`use_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.
---------------------------
Multibucket Object Store
---------------------------
It's possible to configure Nextcloud to distribute it's data over multiple buckets for scalability purpose.
To setup multiple buckets, :code:`config.php` needs to be configured using :code:`'objectstore_multibucket'`
::
'objectstore_multibucket' => array(
'class' => 'Object\\Storage\\Backend\\Class',
'arguments' => array(
// optional, defaults to 64
'num_buckets' => 64,
// will be prefixed by an integer in the range from 0 to (num_nuckets-1)
'bucket' => 'nextcloud_',
...
),
),
Nextcloud will map every user to a range of buckets and save all files for that user in it's respective bucket.
.. note:: Changing the number of buckets for an existing Nextcloud instance is supported but the
mapping from users to buckets is persistent so only newly created users will be mapped to the
updated range of buckets.

4
admin_manual/configuration_server/activity_configuration.rst
View File

@ -19,7 +19,7 @@ The Activity App is shipped and enabled by default. If it is not enabled
simply go to your Nextcloud Apps page to enable it.
Configuring your Nextcloud for the Activity App
----------------------------------------------
-----------------------------------------------
To configure your Nextcloud to send out e-mail notifications a working
:doc:`email_configuration` is mandatory.
@ -29,4 +29,4 @@ Furthermore it is recommended to configure the background job ``Webcron`` or
There is also a configuration option ``activity_expire_days`` available in your
``config.php`` (See :doc:`config_sample_php_parameters`) which allows
you to clean-up older activies from the database.
you to clean-up older activies from the database.

12
admin_manual/configuration_server/antivirus_configuration.rst
View File

@ -77,7 +77,9 @@ and ``freshclam.conf`` until it is running the way you want.
Enabling the Antivirus App for Files
------------------------------------
Simply go to your Nextcloud Apps page to enable it.
Place the ``files_antivirus`` app into the ``apps`` directory of your Nextcloud
server. Then the app shows up on the Nextcloud Apps page where it simply can be
enabled.
.. figure:: ../images/antivirus-app.png
@ -119,8 +121,8 @@ Daemon (Socket)
.. figure:: ../images/antivirus-daemon-socket.png
The ``Stream Length`` value sets the number of bytes read in one pass.
10485760 bytes, or ten megabytes, is the default. This value should be
no larger than the PHP ``memory_limit`` settings, or physical memory if
10485760 bytes, or ten megabytes, is the default. This value should be
no larger than the PHP ``memory_limit`` settings, or physical memory if
``memory_limit`` is set to -1 (no limit).
``Action for infected files found while scanning`` gives you the choice of
@ -131,7 +133,7 @@ Daemon
For the Daemon option you need the hostname or IP address of the remote
server running ClamAV, and the server's port number.
.. figure:: ../images/antivirus-daemon-socket.png
.. figure:: ../images/antivirus-daemon.png
Executable
The Executable option requires the path to ``clamscan``, which is the
@ -141,5 +143,3 @@ Executable
When you are satisfied with how ClamAV is operating, you might want to go
back and change all of your logging to less verbose levels.

62
admin_manual/configuration_server/caching_configuration.rst
View File

@ -16,27 +16,18 @@ if you prefer.**
A PHP opcache stores compiled PHP scripts so they don't need to be re-compiled
every time they are called. PHP bundles the Zend OPcache in core since version
5.5, so you don't need to install an opcache for PHP 5.5+.
5.5, so you don't need to install an opcache manually.
If you are using PHP 5.4, which is the oldest supported PHP version for
Nextcloud, you may install the Alternative PHP Cache (APC). This is both an
opcache and data cache. APC has not been updated since 2012 and is essentially
dead, and PHP 5.4 is old and lags behind later releases. If it is possible
to upgrade to a later PHP release that is the best option.
Data caching is supplied by the Alternative PHP Cache, user (APCu) in PHP
5.5+, Memcached, or Redis.
Data caching is supplied by the user (APCu), Memcached or Redis.
Nextcloud supports multiple memory caching backends, so you can choose the type
of memcache that best fits your needs. The supported caching backends are:
* `APC <http://php.net/manual/en/book.apc.php>`_
A local cache for systems running PHP 5.4.
* `APCu <https://pecl.php.net/package/APCu>`_, APCu 4.0.6 and up required.
A local cache for systems running PHP 5.5 and up.
A local cache for systems.
* `Memcached <http://www.memcached.org/>`_
Distributed cache for multi-server Nextcloud installations.
* `Redis <http://redis.io/>`_, PHP module 2.2.5 and up required.
* `Redis <http://redis.io/>`_, PHP module 2.2.6 and up required.
For distributed caching.
Memcaches must be explicitly configured in Nextcloud by installing
@ -47,24 +38,6 @@ all possible config parameters).
You may use both a local and a distributed cache. Recommended caches are APCu
and Redis. After installing and enabling your chosen memcache, verify that it is
active by running :ref:`label-phpinfo`.
APC
---
APC is only for systems running PHP 5.4 and older. The oldest supported PHP
version in Nextcloud is 5.4.
.. note:: RHEL 6 and CentOS 6 ship with PHP 5.3 and must be upgraded to PHP
5.4 to run Nextcloud. See :doc:`../installation/php_54_installation`.
On Red Hat/CentOS/Fedora systems running PHP 5.4, install ``php-pecl-apc``. On
Debian/Ubuntu/Mint systems install ``php-apc``. Then restart your Web server.
After restarting your Web server, add this line to your ``config.php`` file::
'memcache.local' => '\OC\Memcache\APC',
Refresh your Nextcloud admin page, and the cache warning should disappear.
APCu
----
@ -72,9 +45,10 @@ APCu
PHP 5.5 and up include the Zend OPcache in core, and on most Linux
distributions it is enabled by default. However, it does
not bundle a data cache. APCu is a data cache, and it is available in most
Linux distributions. On Red Hat/CentOS/Fedora systems running PHP 5.5 and up
install ``php-pecl-apcu``. On Debian/Ubuntu/Mint systems install ``php5-apcu``.
On Ubuntu 14.04LTS, the APCu version is 4.0.2, which is too old to use with Nextcloud. Nextcloud requires 4.0.6+. You may install 4.0.7 from Ubuntu backports with this command::
Linux distributions. On Red Hat/CentOS/Fedora systems install
``php-pecl-apcu``. On Debian/Ubuntu/Mint systems install ``php5-apcu`` or ``php7.0-apcu``.
On Ubuntu 14.04 LTS, the APCu version (4.0.2) is too old to use with Nextcloud (requires 4.0.6+).
You may install 4.0.7 from Ubuntu backports with this command::
apt-get install php5-apcu/trusty-backports
@ -135,11 +109,11 @@ as a local cache for :doc:`Transactional File Locking
<../configuration_files/files_locking_transactional>` because it guarantees
that cached objects are available for as long as they are needed.
The Redis PHP module must be version 2.2.5+. If you are running a Linux
The Redis PHP module must be version 2.2.6+. If you are running a Linux
distribution that does not package the supported versions of this module, or
does not package Redis at all, see :ref:`install_redis_label`.
On Debian/Ubuntu/Mint install ``redis-server`` and ``php5-redis``. The installer
On Debian/Ubuntu/Mint install ``redis-server`` and ``php5-redis`` or ``php7.0-redis``. The installer
will automatically launch ``redis-server`` and configure it to launch at
startup.
@ -174,8 +148,13 @@ recommended if Redis is running on the same system as Nextcloud) use this exampl
'redis' => array(
'host' => '/var/run/redis/redis.sock',
'port' => 0,
'dbindex' => 0,
'password' => 'secret',
'timeout' => 1.5,
),
Only "host" and "port" variables are required, the other ones are optional.
Redis is very configurable; consult `the Redis documentation
<http://redis.io/documentation>`_ to learn more.
@ -240,13 +219,10 @@ These instructions are adaptable for any distro that does not package the
supported version, or that does not package Redis at all, such as SUSE Linux
Enterprise Server and Red Hat Enterprise Linux.
The Redis PHP module must be at least version 2.2.5. Please note that
the Redis PHP module versions 2.2.5 - 2.2.7 will only work for:
::
PHP version 6.0.0 or older
PHP version 5.2.0 or newer
The Redis PHP module must be at least version 2.2.6. Please note that
the Redis PHP module versions 2.2.x will only work for PHP 5.6.x.
For PHP 7.0 and PHP 7.1 use Redis PHP module 3.1.x or later.
See `<https://pecl.php.net/package/redis>`_

318
admin_manual/configuration_server/config_sample_php_parameters.rst
View File

@ -17,11 +17,11 @@ Nextcloud supports loading configuration parameters from multiple files.
You can add arbitrary files ending with :file:`.config.php` in the :file:`config/`
directory, for example you could place your email server configuration
in :file:`email.config.php`. This allows you to easily create and manage
custom configurations, or to divide a large complex configuration file
into a set of smaller files. These custom files are not overwritten by
custom configurations, or to divide a large complex configuration file
into a set of smaller files. These custom files are not overwritten by
Nextcloud, and the values in these files take precedence over :file:`config.php`.
.. The following section is auto-generated from
.. The following section is auto-generated from
.. https://github.com/nextcloud/server/blob/master/config/config.sample.php
.. Do not edit this file; edit the source file in core
.. DEFAULT_SECTION_START
@ -78,8 +78,10 @@ You can specify:
'datadirectory' => '/var/www/nextcloud/data',
Where user files are stored; this defaults to ``data/`` in the Nextcloud
directory. The SQLite database is also stored here, when you use SQLite.
Where user files are stored. The SQLite database is also stored here, when
you use SQLite.
Default to ``data/`` in the Nextcloud directory.
::
@ -99,7 +101,8 @@ Available:
- sqlite (SQLite3)
- mysql (MySQL/MariaDB)
- pgsql (PostgreSQL)
- oci (Oracle)
Defaults to ``sqlite``
::
@ -138,6 +141,8 @@ you shouldn't need to change it.
Prefix for the Nextcloud tables in the database.
Default to ``oc_``
::
'installed' => false,
@ -146,6 +151,8 @@ Indicates whether the Nextcloud instance was installed successfully; ``true``
indicates a successful installation, and ``false`` indicates an unsuccessful
installation.
Defaults to ``false``
.. DEFAULT_SECTION_END
.. Generated content above. Don't change this.
@ -219,6 +226,8 @@ French. It overrides automatic language detection on public pages like login
or shared items. User's language preferences configured under "personal ->
language" override this setting after they have logged in.
Defaults to ``en``
::
'defaultapp' => 'files',
@ -229,6 +238,8 @@ gallery. You can use a comma-separated list of app names, so if the first
app is not enabled for a user then Nextcloud will try the second one, and so
on. If no enabled apps are found it defaults to the Files app.
Defaults to ``files``
::
'knowledgebaseenabled' => true,
@ -244,6 +255,8 @@ Nextcloud Web interface). ``false`` removes the Help item.
page, on user's Personal pages and are used by some apps (contacts, mail,
etc). ``false`` disables them.
Defaults to ``true``
::
'allow_user_to_change_display_name' => true,
@ -255,16 +268,18 @@ pages), and ``false`` prevents them from changing their display names.
'remember_login_cookie_lifetime' => 60*60*24*15,
Lifetime of the remember login cookie, which is set when the user clicks the
``remember`` checkbox on the login screen. The default is 15 days, expressed
in seconds.
Lifetime of the remember login cookie, which is set when the user clicks
the ``remember`` checkbox on the login screen.
Defaults to ``60*60*24*15`` seconds (15 days)
::
'session_lifetime' => 60 * 60 * 24,
The lifetime of a session after inactivity; the default is 24 hours,
expressed in seconds.
The lifetime of a session after inactivity.
Defaults to ``60*60*24`` seconds (24 hours)
::
@ -274,6 +289,8 @@ Enable or disable session keep-alive when a user is logged in to the Web UI.
Enabling this sends a "heartbeat" to the server to keep it from timing out.
Defaults to ``true``
::
'token_auth_enforced' => false,
@ -282,6 +299,8 @@ Enforce token authentication for clients, which blocks requests using the user
password for enhanced security. Users need to generate tokens in personal settings
which can be used as passwords on their clients.
Defaults to ``false``
::
'auth.bruteforce.protection.enabled' => true,
@ -290,6 +309,8 @@ Whether the bruteforce protection shipped with Nextcloud should be enabled or no
Disabling this is discouraged for security reasons.
Defaults to ``true``
::
'skeletondirectory' => '/path/to/nextcloud/core/skeleton',
@ -298,6 +319,8 @@ The directory where the skeleton files are located. These files will be
copied to the data directory of new users. Leave empty to not copy any
skeleton files.
Defaults to ``core/skeleton`` in the Nextcloud directory.
::
'user_backends' => array(
@ -342,15 +365,19 @@ of course.
FROM address that overrides the built-in ``sharing-noreply`` and
``lostpassword-noreply`` FROM addresses.
Defaults to different from addresses depending on the feature.
::
'mail_smtpdebug' => false,
Enable SMTP class debugging.
Defaults to ``false``
::
'mail_smtpmode' => 'sendmail',
'mail_smtpmode' => 'php',
Which mode to use for sending mail: ``sendmail``, ``smtp``, ``qmail`` or
``php``.
@ -367,6 +394,8 @@ the server, with ``/usr/sbin/sendmail`` installed on your Unix system.
For ``qmail`` the binary is /var/qmail/bin/sendmail, and it must be installed
on your Unix system.
Defaults to ``php``
::
'mail_smtphost' => '127.0.0.1',
@ -376,12 +405,16 @@ server host. This may contain multiple hosts separated by a semi-colon. If
you need to specify the port number append it to the IP address separated by
a colon, like this: ``127.0.0.1:24``.
Defaults to ``127.0.0.1``
::
'mail_smtpport' => 25,
This depends on ``mail_smtpmode``. Specify the port for sending mail.
Defaults to ``25``
::
'mail_smtptimeout' => 10,
@ -390,6 +423,8 @@ This depends on ``mail_smtpmode``. This sets the SMTP server timeout, in
seconds. You may need to increase this if you are running an anti-malware or
spam scanner.
Defaults to ``10`` seconds
::
'mail_smtpsecure' => '',
@ -397,6 +432,8 @@ spam scanner.
This depends on ``mail_smtpmode``. Specify when you are using ``ssl`` or
``tls``, or leave empty for no encryption.
Defaults to ``''`` (empty string)
::
'mail_smtpauth' => false,
@ -404,12 +441,16 @@ This depends on ``mail_smtpmode``. Specify when you are using ``ssl`` or
This depends on ``mail_smtpmode``. Change this to ``true`` if your mail
server requires authentication.
Defaults to ``false``
::
'mail_smtpauthtype' => 'LOGIN',
This depends on ``mail_smtpmode``. If SMTP authentication is required, choose
the authentication type as ``LOGIN`` (default) or ``PLAIN``.
the authentication type as ``LOGIN`` or ``PLAIN``.
Defaults to ``LOGIN``
::
@ -418,6 +459,8 @@ the authentication type as ``LOGIN`` (default) or ``PLAIN``.
This depends on ``mail_smtpauth``. Specify the username for authenticating to
the SMTP server.
Defaults to ``''`` (empty string)
::
'mail_smtppassword' => '',
@ -425,6 +468,8 @@ the SMTP server.
This depends on ``mail_smtpauth``. Specify the password for authenticating to
the SMTP server.
Default to ``''`` (empty string)
Proxy Configurations
--------------------
@ -469,6 +514,8 @@ expression for the remote IP address. For example, defining a range of IP
addresses starting with ``10.0.0.`` and ending with 1 to 3:
``^10\.0\.0\.[1-3]$``
Defaults to ``''`` (empty string)
::
'overwrite.cli.url' => '',
@ -478,6 +525,8 @@ are generated within Nextcloud using any kind of command line tools (cron or
occ). The value should contain the full base URL:
``https://www.example.com/nextcloud``
Defaults to ``''`` (empty string)
::
'htaccess.RewriteBase' => '/',
@ -504,12 +553,28 @@ conditions are met Nextcloud uses URLs without index.php in it:
- `mod_rewrite` is installed
- `mod_env` is installed
Defaults to ``''`` (empty string)
::
'htaccess.IgnoreFrontController' => false,
For server setups, that don't have `mod_env` enabled or restricted (e.g. suEXEC)
this parameter has to be set to true and will assume mod_rewrite.
Please check, if `mod_rewrite` is active and functional before setting this
parameter and you updated your .htaccess with `occ maintenance:update:htaccess`.
Otherwise your nextcloud installation might not be reachable anymore.
For example, try accessing resources by leaving out `index.php` in the URL.
::
'proxy' => '',
The URL of your proxy server, for example ``proxy.example.com:8081``.
Defaults to ``''`` (empty string)
::
'proxyuserpwd' => '',
@ -518,6 +583,8 @@ The optional authentication for the proxy to use to connect to the internet.
The format is: ``username:password``.
Defaults to ``''`` (empty string)
Deleted Items (trash bin)
-------------------------
@ -559,6 +626,8 @@ Available values:
* ``disabled``
trash bin auto clean disabled, files and folders will be kept forever
Defaults to ``auto``
File versions
-------------
@ -599,6 +668,8 @@ Available values:
* ``disabled``
versions auto clean disabled, versions will be kept forever
Defaults to ``auto``
Nextcloud Verifications
-----------------------
@ -614,6 +685,8 @@ Checks an app before install whether it uses private APIs instead of the
proper public APIs. If this is set to true it will only allow to install or
enable apps that pass this check.
Defaults to ``false``
::
'updatechecker' => true,
@ -621,18 +694,36 @@ enable apps that pass this check.
Check if Nextcloud is up-to-date and shows a notification if a new version is
available.
Defaults to ``true``
::
'updater.server.url' => 'https://updates.nextcloud.org/server/',
'updater.server.url' => 'https://updates.nextcloud.com/updater_server/',
URL that Nextcloud should use to look for updates
Defaults to ``https://updates.nextcloud.com/updater_server/``
::
'updater.release.channel' => 'stable',
The channel that Nextcloud should use to look for updates
Supported values:
- ``daily``
- ``beta``
- ``stable``
- ``production``
::
'has_internet_connection' => true,
Is Nextcloud connected to the Internet or running in a closed network?
Defaults to ``true``
::
'check_for_working_webdav' => true,
@ -648,6 +739,8 @@ Allows Nextcloud to verify a working .well-known URL redirects. This is done
by attempting to make a request from JS to
https://your-domain.com/.well-known/caldav/
Defaults to ``true``
::
'check_for_working_htaccess' => true,
@ -659,6 +752,8 @@ If it is not, then any options controlled by ``.htaccess``, such as large
file uploads, will not work. It also runs checks on the ``data/`` directory,
which verifies that it can't be accessed directly through the Web server.
Defaults to ``true``
::
'config_is_read_only' => false,
@ -671,6 +766,8 @@ all options via the Web interface. Furthermore, when updating Nextcloud
it is required to make the configuration file writable again for the update
process.
Defaults to ``false``
Logging
-------
@ -686,6 +783,8 @@ If syslogging is desired, set this parameter to ``syslog``.
Setting this parameter to ``errorlog`` will use the PHP error_log function
for logging.
Defaults to ``file``
::
'logfile' => '/var/log/nextcloud.log',
@ -701,6 +800,8 @@ Defaults to ``[datadirectory]/nextcloud.log``
Loglevel to start logging at. Valid values are: 0 = Debug, 1 = Info, 2 =
Warning, 3 = Error, and 4 = Fatal. The default value is Warning.
Defaults to ``2``
::
'syslog_tag' => 'Nextcloud',
@ -739,13 +840,18 @@ Defaults to an empty array.
This uses PHP.date formatting; see http://php.net/manual/en/function.date.php
Defaults to ISO 8601 ``2005-08-15T15:52:01+00:00`` - see \DateTime::ATOM
(https://secure.php.net/manual/en/class.datetime.php#datetime.constants.atom)
::
'logtimezone' => 'Europe/Berlin',
The default timezone for logfiles is UTC. You may change this; see
The timezone for logfiles. You may change this; see
http://php.net/manual/en/timezones.php
Defaults to ``UTC``
::
'log_query' => false,
@ -759,6 +865,8 @@ debugging, as your logfile will become huge.
Log successful cron runs.
Defaults to ``true``
::
'log_rotate_size' => false,
@ -769,6 +877,8 @@ or no rotation. Specify a size in bytes, for example 104857600 (100 megabytes
old logfile reaches your limit. If a rotated log file is already present, it
will be overwritten.
Defaults to ``0`` (no rotation)
Alternate Code Locations
------------------------
@ -778,7 +888,7 @@ Some of the Nextcloud code may be stored in alternate locations.
::
'customclient_desktop' =>
'https://nextcloud.com/install/',
'https://nextcloud.com/install/#install-clients',
'customclient_android' =>
'https://play.google.com/store/apps/details?id=com.nextcloud.client',
'customclient_ios' =>
@ -787,6 +897,11 @@ Some of the Nextcloud code may be stored in alternate locations.
This section is for configuring the download links for Nextcloud clients, as
seen in the first-run wizard and on Personal pages.
Defaults to
* Desktop client: ``https://nextcloud.com/install/#install-clients``
* Android client: ``https://play.google.com/store/apps/details?id=com.nextcloud.client``
* iOS client : ``https://itunes.apple.com/us/app/nextcloud/id1125420102?mt=8``
Apps
----
@ -799,21 +914,7 @@ Options for the Apps folder, Apps store, and App code checker.
When enabled, admins may install apps from the Nextcloud app store.
::
'appstoreurl' => 'https://api.owncloud.com/v1',
The URL of the appstore to use.
::
'appstore.experimental.enabled' => false,
Whether to show experimental apps in the appstore interface
Experimental apps are not checked for security issues and are new or known
to be unstable and under heavy development. Installing these can cause data
loss or security breaches.
Defaults to ``true``
::
@ -840,6 +941,8 @@ Checks an app before install whether it uses private APIs instead of the
proper public APIs. If this is set to true it will only allow to install or
enable apps that pass this check.
Defaults to ``false``
@ -865,6 +968,8 @@ By default, Nextcloud can generate previews for the following filetypes:
Valid values are ``true``, to enable previews, or
``false``, to disable previews
Defaults to ``true``
::
'preview_max_x' => 2048,
@ -872,6 +977,8 @@ Valid values are ``true``, to enable previews, or
The maximum width, in pixels, of a preview. A value of ``null`` means there
is no limit.
Defaults to ``2048``
::
'preview_max_y' => 2048,
@ -879,6 +986,8 @@ is no limit.
The maximum height, in pixels, of a preview. A value of ``null`` means there
is no limit.
Defaults to ``2048``
::
'preview_max_scale_factor' => 10,
@ -888,17 +997,17 @@ preview system generates blurry previews, you might want to consider setting
a maximum scale factor. By default, pictures are upscaled to 10 times the
original size. A value of ``1`` or ``null`` disables scaling.
Defaults to ``2``
::
'preview_max_filesize_image' => 50,
max file size for generating image previews with imagegd (default behaviour)
If the image is bigger, it'll try other preview generators,
but will most likely show the default mimetype icon
If the image is bigger, it'll try other preview generators, but will most
likely show the default mimetype icon. Set to -1 for no limit.
Value represents the maximum filesize in megabytes
Default is 50
Set to -1 for no limit
Defaults to ``50`` megabytes
::
@ -906,6 +1015,8 @@ Set to -1 for no limit
custom path for LibreOffice/OpenOffice binary
Defaults to ``''`` (empty string)
::
'preview_office_cl_parameters' =>
@ -914,6 +1025,8 @@ custom path for LibreOffice/OpenOffice binary
Use this if LibreOffice/OpenOffice requires additional arguments.
Defaults to ``''`` (empty string)
::
'enabledPreviewProviders' => array(
@ -929,17 +1042,6 @@ Use this if LibreOffice/OpenOffice requires additional arguments.
Only register providers that have been explicitly enabled
The following providers are enabled by default:
- OC\\Preview\\PNG
- OC\\Preview\\JPEG
- OC\\Preview\\GIF
- OC\\Preview\\BMP
- OC\\Preview\\XBitmap
- OC\\Preview\\MarkDown
- OC\\Preview\\MP3
- OC\\Preview\\TXT
The following providers are disabled by default due to performance or privacy
concerns:
@ -970,6 +1072,17 @@ The following providers are not available in Microsoft Windows:
- OC\\Preview\\OpenDocument
- OC\\Preview\\StarOffice
Defaults to the following providers:
- OC\\Preview\\BMP
- OC\\Preview\\GIF
- OC\\Preview\\JPEG
- OC\\Preview\\MarkDown
- OC\\Preview\\MP3
- OC\\Preview\\PNG
- OC\\Preview\\TXT
- OC\\Preview\\XBitmap
LDAP
----
@ -986,6 +1099,8 @@ minutes. Setting it to 0 disables the feature.
See command line (occ) methods ``ldap:show-remnants`` and ``user:delete``
Defaults to ``51`` minutes
Comments
--------
@ -1000,6 +1115,8 @@ Replaces the default Comments Manager Factory. This can be utilized if an
own or 3rdParty CommentsManager should be used that – for instance – uses the
filesystem instead of the database to keep the comments.
Defaults to ``\OC\Comments\ManagerFactory``
::
'systemtags.managerFactory' => '\OC\SystemTag\ManagerFactory',
@ -1008,6 +1125,8 @@ Replaces the default System Tags Manager Factory. This can be utilized if an
own or 3rdParty SystemTagsManager should be used that – for instance – uses the
filesystem instead of the database to keep the comments.
Defaults to ``\OC\SystemTag\ManagerFactory``
Maintenance
-----------
@ -1026,6 +1145,8 @@ doing some maintenance work, you need to set the value of the maintenance
parameter to true. Please keep in mind that users who are already logged-in
are kicked out of Nextcloud instantly.
Defaults to ``false``
::
'singleuser' => false,
@ -1033,6 +1154,8 @@ are kicked out of Nextcloud instantly.
When set to ``true``, the Nextcloud instance will be unavailable for all
users who are not in the ``admin`` group.
Defaults to ``false``
SSL
---
@ -1045,6 +1168,8 @@ SSL
Extra SSL options to be used for configuration.
Defaults to an empty array.
::
'enable_certificate_management' => false,
@ -1056,7 +1181,6 @@ Memory caching backend configuration
Available cache backends:
* ``\OC\Memcache\APC`` Alternative PHP Cache backend
* ``\OC\Memcache\APCu`` APC user backend
* ``\OC\Memcache\ArrayCache`` In-memory array-based backend (not recommended)
* ``\OC\Memcache\Memcached`` Memcached backend
@ -1079,6 +1203,8 @@ Memory caching backend for locally stored data
* Used for host-specific data, e.g. file paths
Defaults to ``none``
::
'memcache.distributed' => '\OC\Memcache\Memcached',
@ -1088,6 +1214,8 @@ Memory caching backend for distributed data
* Used for installation-specific data, e.g. database caching
* If unset, defaults to the value of memcache.local
Defaults to ``none``
::
'redis' => array(
@ -1150,24 +1278,28 @@ Location of the cache folder, defaults to ``data/$user/cache`` where
``$cache_path/$user`` where ``$cache_path`` is the configured cache directory
and ``$user`` is the user.
Defaults to ``''`` (empty string)
::
'cache_chunk_gc_ttl' => 86400, // 60*60*24 = 1 day
'cache_chunk_gc_ttl' => 60*60*24,
TTL of chunks located in the cache folder before they're removed by
garbage collection (in seconds). Increase this value if users have
issues uploading very large files via the Nextcloud Client as upload isn't
completed within one day.
Defaults to ``60*60*24`` (1 day)
Using Object Store with Nextcloud
---------------------------------
::
'objectstore' => array(
'objectstore' => [
'class' => 'OC\\Files\\ObjectStore\\Swift',
'arguments' => array(
'arguments' => [
// trystack will user your facebook id as the user name
'username' => 'facebook100000123456789',
// in the trystack dashboard go to user -> settings -> API Password to
@ -1175,6 +1307,8 @@ Using Object Store with Nextcloud
'password' => 'Secr3tPaSSWoRdt7',
// must already exist in the objectstore, name can be different
'container' => 'nextcloud',
// prefix to prepend to the fileid, default is 'oid:urn:'
'objectPrefix' => 'oid:urn:',
// create the container if it does not exist. default is false
'autocreate' => true,
// required, dev-/trystack defaults to 'RegionOne'
@ -1188,8 +1322,8 @@ Using Object Store with Nextcloud
'serviceName' => 'swift',
// The Interface / url Type, optional
'urlType' => 'internal'
),
),
],
],
This example shows how to configure Nextcloud to store all files in a
swift object storage.
@ -1221,6 +1355,8 @@ Replaces the default Share Provider Factory. This can be utilized if
own or 3rdParty Share Providers be used that – for instance – uses the
filesystem instead of the database to keep the share information.
Defaults to ``\OC\Share20\ProviderFactory``
All other configuration options
-------------------------------
@ -1242,6 +1378,35 @@ encryption in MySQL or specify a custom wait timeout on a cheap hoster.
sqlite3 journal mode can be specified using this configuration parameter -
can be 'WAL' or 'DELETE' see for more details https://www.sqlite.org/wal.html
::
'mysql.utf8mb4' => false,
If this setting is set to true MySQL can handle 4 byte characters instead of
3 byte characters
MySQL requires a special setup for longer indexes (> 767 bytes) which are
needed:
[mysqld]
innodb_large_prefix=true
innodb_file_format=barracuda
innodb_file_per_table=true
Tables will be created with
* character set: utf8mb4
* collation: utf8mb4_bin
* row_format: compressed
See:
https://dev.mysql.com/doc/refman/5.7/en/charset-unicode-utf8mb4.html
https://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html#sysvar_innodb_large_prefix
https://mariadb.com/kb/en/mariadb/xtradbinnodb-server-system-variables/#innodb_large_prefix
http://www.tocker.ca/2013/10/31/benchmarking-innodb-page-compression-performance.html
http://mechanics.flite.com/blog/2014/07/29/using-innodb-large-prefix-to-avoid-error-1071/
WARNING: EXPERIMENTAL
::
'supportedDatabases' => array(
@ -1259,6 +1424,11 @@ Available:
- pgsql (PostgreSQL)
- oci (Oracle)
Defaults to the following databases:
- sqlite (SQLite3)
- mysql (MySQL)
- pgsql (PostgreSQL)
::
'tempdirectory' => '/tmp/nextcloudtemp',
@ -1286,12 +1456,16 @@ with this name. ``.htaccess`` is blocked by default.
WARNING: USE THIS ONLY IF YOU KNOW WHAT YOU ARE DOING.
Defaults to ``array('.htaccess')``
::
'share_folder' => '/',
Define a default folder for shared files and folders other than root.
Defaults to ``/``
::
'theme' => '',
@ -1300,6 +1474,8 @@ If you are applying a theme to Nextcloud, enter the name of the theme here.
The default location for themes is ``nextcloud/themes/``.
Defaults to the theming app which is shipped since Nextcloud 9
::
'cipher' => 'AES-256-CFB',
@ -1309,7 +1485,7 @@ AES-256-CFB are supported.
::
'minimum.supported.desktop.version' => '1.7.0',
'minimum.supported.desktop.version' => '2.0.0',
The minimum Nextcloud desktop client version that will be allowed to sync with
this server instance. All connections made from earlier clients will be denied
@ -1320,6 +1496,8 @@ When changing this, note that older unsupported versions of the Nextcloud deskto
client may not function as expected, and could lead to permanent data loss for
clients or other unexpected results.
Defaults to ``2.0.0``
::
'quota_include_external_storage' => false,
@ -1327,6 +1505,8 @@ clients or other unexpected results.
EXPERIMENTAL: option whether to include external storage in quota
calculation, defaults to false.
Defaults to ``false``
::
'filesystem_check_changes' => 0,
@ -1342,6 +1522,8 @@ filesystem
1 -> Check each file or folder at most once per request, recommended for
general use if outside changes might happen.
Defaults to ``0``
::
'part_file_in_storage' => true,
@ -1351,6 +1533,8 @@ same storage as the upload target. Setting this to false will store the part
files in the root of the users folder which might be required to work with certain
external storage setups that have limited rename capabilities.
Defaults to ``true``
::
'mount_file' => '/var/www/nextcloud/data/mount.json',
@ -1358,6 +1542,8 @@ external storage setups that have limited rename capabilities.
Where ``mount.json`` file should be stored, defaults to ``data/mount.json``
in the Nextcloud directory.
Defaults to ``data/mount.json`` in the Nextcloud directory.
::
'filesystem_cache_readonly' => false,
@ -1365,6 +1551,8 @@ in the Nextcloud directory.
When ``true``, prevent Nextcloud from changing the cache due to changes in
the filesystem for all storage.
Defaults to ``false``
::
'secret' => '',
@ -1380,6 +1568,7 @@ List of trusted proxy servers
If you configure these also consider setting `forwarded_for_headers` which
otherwise defaults to `HTTP_X_FORWARDED_FOR` (the `X-Forwarded-For` header).
Defaults to an empty array.
::
@ -1392,7 +1581,7 @@ Headers that should be trusted as client IP address in combination with
If set incorrectly, a client can spoof their IP address as visible to
Nextcloud, bypassing access controls and making logs useless!
Defaults to 'HTTP_X_FORWARED_FOR' if unset
Defaults to ``'HTTP_X_FORWARED_FOR'``
::
@ -1402,8 +1591,10 @@ max file size for animating gifs on public-sharing-site.
If the gif is bigger, it'll show a static preview
Value represents the maximum filesize in megabytes. Default is ``10``. Set to
``-1`` for no limit.
Value represents the maximum filesize in megabytes. Set to ``-1`` for
no limit.
Defaults to ``10`` megabytes
::
@ -1419,15 +1610,18 @@ be caused by concurrent operations. Mainly relevant for
very large installations with many users working with
shared files.
Defaults to ``true``
::
'filelocking.ttl' => 3600,
'filelocking.ttl' => 60*60,
Set the time-to-live for locks in secconds.
Any lock older than this will be automatically cleaned up.
If not set this defaults to either 1 hour or the php max_execution_time, whichever is higher.
Defaults to ``60*60`` seconds (1 hour) or the php
max_execution_time, whichever is higher.
::
@ -1438,6 +1632,8 @@ Memory caching backend for file locking
Because most memcache backends can clean values without warning using redis
is highly recommended to *avoid data loss*.
Defaults to ``none``
::
'upgrade.disable-web' => false,
@ -1453,6 +1649,8 @@ Set this Nextcloud instance to debugging mode
Only enable this for local development and not in production environments
This will disable the minifier and outputs some additional debug information
Defaults to ``false``
::
'data-fingerprint' => '',
@ -1467,6 +1665,8 @@ To set this to a new value.
Updating/Deleting this value can make connected clients stall until
the user has resolved conflicts.
Defaults to ``''`` (empty string)
::
'copied_sample_config' => true,

6
admin_manual/configuration_server/email_configuration.rst
View File

@ -142,16 +142,14 @@ If you want to send email using a local or remote SMTP server it is necessary
to enter the name or IP address of the server, optionally followed by a colon
separated port number, e.g. **:425**. If this value is not given the default
port 25/tcp will be used unless you change that by modifying the
**mail_smtpport** parameter. Multiple servers can be entered, separated by
semicolons:
**mail_smtpport** parameter.
::
<?php
"mail_smtpmode" => "smtp",
"mail_smtphost" => "smtp-1.server.dom;smtp-2.server.dom:425",
"mail_smtpport" => 25,
"mail_smtphost" => "smtp.server.dom:425",
or

BIN
admin_manual/configuration_server/images/saml_app_overview.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 124 KiB

7
admin_manual/configuration_server/index.rst
View File

@ -8,7 +8,7 @@ Nextcloud Server Configuration
security_setup_warnings
occ_command
activity_configuration
antivirus_configuration
sso_configuration
caching_configuration
background_jobs_configuration
config_sample_php_parameters
@ -21,7 +21,8 @@ Nextcloud Server Configuration
harden_server
reverse_proxy_configuration
thirdparty_php_configuration
js_css_asset_management_configuration
automatic_configuration
oc_server_tuning
server_tuning
theming
.. Intentional disabled antivirus_configuration

27
admin_manual/configuration_server/js_css_asset_management_configuration.rst
View File

@ -1,27 +0,0 @@
JavaScript and CSS Asset Management
===================================
In production environments, JavaScript and CSS files should be delivered in a concatenated and compressed format.
Nextcloud can automatically collect all JavaScript and CSS files, aggregate and compress them to then save the result in a folder called 'assets' which can be found in the folder where Nextcloud has been installed.
If your Web server has write access to your Nextcloud installation, then the 'assets' folder will be automatically created for you, otherwise, you need to create it yourself before enabling that option and you must give write access to your Web server user.
Assets found in that folder will from now on be served as static files by your Web server and will be automatically refreshed whenever Nextcloud or one of its apps is updated.
It's important to note that apps installed via git might not always update their version number with every commit and this could lead to an out-of-sync asset folder.
It is not recommended to enable asset-pipelining when using apps pulled via git.
Parameters
----------
::
<?php
$CONFIG = array (
...
'asset-pipeline.enabled' => true,
...
);
You can set this parameter in the :file:`config/config.php`

4
admin_manual/configuration_server/language_configuration.rst
View File

@ -8,10 +8,10 @@ starts with a given language, you can use the **default_language** parameter.
Please keep in mind, that this will not effect a users language preference,
which has been configured under "personal -> language" once he has logged in.
Please check :file:`settings/languageCodes.php` for the list of supported language
Please check `Transifex language codes
<https://www.transifex.com/explore/languages/>`_ for the list of valid language
codes.
Parameters
----------

4
admin_manual/configuration_server/logging_configuration.rst
View File

@ -19,8 +19,8 @@ By default the log level is set to **2** (WARN). Use **DEBUG** when you have a p
Logging level parameters are set in the :file:`config/config.php` file, or on the Admin page of your Nextcloud Web GUI.
ownCloud
~~~~~~~~
Nextcloud
~~~~~~~~~
All log information will be written to a separate log file which can be
viewed using the log viewer on your Admin page. By default, a log

65
admin_manual/configuration_server/occ_command.rst
View File

@ -31,7 +31,6 @@ occ Command Directory
* :ref:`logging_commands_label`
* :ref:`maintenance_commands_label`
* :ref:`security_commands_label`
* :ref:`shibboleth_label`
* :ref:`trashbin_label`
* :ref:`user_commands_label`
* :ref:`versions_label`
@ -55,9 +54,9 @@ The HTTP user is different on the various Linux distributions. See
If your HTTP server is configured to use a different PHP version than the
default (/usr/bin/php), ``occ`` should be run with the same version. For
example, in CentOS 6.5 with SCL-PHP54 installed, the command looks like this::
example, in CentOS 6.5 with SCL-PHP56 installed, the command looks like this::
sudo -u apache /opt/rh/php54/root/usr/bin/php /var/www/html/nextcloud/occ
sudo -u apache /opt/rh/php56/root/usr/bin/php /var/www/html/nextcloud/occ
Running ``occ`` with no options lists all commands and options, like this
example on Ubuntu::
@ -153,6 +152,32 @@ This output option is available on all list and list-like commands:
``status``, ``check``, ``app:list``, ``config:list``, ``encryption:status``
and ``encryption:list-modules``
Enabling autocompletion
-----------------------
.. note:: This currently only works, if the user you use to execute the occ commands has a profile.
``www-data`` in most cases is ``nologon`` and therefor can **not** use this.
Since Nextcloud 11 autocompletion is available for bash (and bash based consoles).
To enable it, you have to run **one** of the following commands::
# BASH ~4.x, ZSH
source <(/var/www/html/nextcloud/occ _completion --generate-hook)
# BASH ~3.x, ZSH
/var/www/html/nextcloud/occ _completion --generate-hook | source /dev/stdin
# BASH (any version)
eval $(/var/www/html/nextcloud/occ _completion --generate-hook)
This will allow you to use autocompletion with the full path ``/var/www/html/nextcloud/occ <tab>``.
If you also want to use autocompletion on occ from within the directory without using the full path,
you need to specify ``--programm occ`` after the ``--generate-hook``.
If you want the completion to apply automatically for all new shell sessions, add the command to your
shell's profile (eg. ``~/.bash_profile`` or ``~/.zshrc``).
.. _apps_commands_label:
Apps Commands
@ -654,6 +679,7 @@ Commands for managing external storage::
files_external:list List configured mounts
files_external:option Manage mount options for a mount
files_external:verify Verify mount configuration
files_external:notify Listen for active update notifications for a configured external mount
These commands replicate the functionality in the Nextcloud Web GUI, plus two new
features: ``files_external:export`` and ``files_external:import``.
@ -902,20 +928,6 @@ Remove a certificate::
sudo -u www-data php occ security:remove [certificate name]
.. _shibboleth_label:
Shibboleth Modes (Enterprise Edition only)
------------------------------------------
.. note::
This command is only available when the "Shibboleth user backend" app
(``user_shibboleth``) is enabled.
``shibboleth:mode`` sets your Shibboleth mode to ``notactive``,
``autoprovision``, or ``ssoonly``::
shibboleth:mode [mode]
.. _trashbin_label:
Trashbin
@ -1211,13 +1223,9 @@ List all options, like this example on CentOS Linux::
sudo -u apache php occ upgrade -h
Usage:
upgrade [--skip-migration-test] [--dry-run] [--no-app-disable]
upgrade [--no-app-disable]
Options:
--skip-migration-test skips the database schema migration simulation and
update directly
--dry-run only runs the database schema migration simulation, do
not actually update
--no-app-disable skips the disable of third party apps
--help (-h) Display this help message.
--quiet (-q) Do not output any message.
@ -1277,19 +1285,6 @@ or to use in a bug report::
Update failed
Turned off maintenance mode
Before completing the upgrade, Nextcloud first runs a simulation by copying all
database tables to new tables, and then performs the upgrade on them, to ensure
that the upgrade will complete correctly. The copied tables are deleted after
the upgrade. This takes twice as much time, which on large installations can be
many hours, so you can omit this step with the ``--skip-migration-test``
option::
sudo -u www-data php occ upgrade --skip-migration-test
You can perform this simulation manually with the ``--dry-run`` option::
sudo -u www-data php occ upgrade --dry-run
.. _two_factor_auth_label:
Two-factor Authentication

11
admin_manual/configuration_server/security_setup_warnings.rst
View File

@ -8,6 +8,12 @@ might see, and what to do about them.
.. figure:: ../images/security-setup-warning-1.png
You can use the `Nextcloud Security Scan <https://scan.nextcloud.com>`_ to see
if your system is up to date and well secured. We have ran this scan over public
IP addresses in the past to try and reach out to `extremely outdated systems <https://nextcloud.com/blog/nextcloud-releases-security-scanner-to-help-protect-private-clouds/>`_
and might again in the future. Please, protect your privacy and keep your server
up to date! Privacy means little without security.
Cache Warnings
--------------
@ -15,10 +21,9 @@ Cache Warnings
configure a memcache if available." Nextcloud supports multiple php caching
extensions:
* APC (PHP 5.4 only)
* APCu (PHP 5.5+, minimum required PHP extension version 4.0.6)
* APCu (minimum required PHP extension version 4.0.6)
* Memcached
* Redis (minimum required php extension version: 2.2.5)
* Redis (minimum required PHP extension version: 2.2.6)
You will see this warning if you have no caches installed and enabled, or if
your cache does not have the required minimum version installed; older versions

30
admin_manual/configuration_server/oc_server_tuning.rst → admin_manual/configuration_server/server_tuning.rst
View File

@ -8,12 +8,6 @@ Using cron to perform background jobs
See :doc:`background_jobs_configuration` for a description and the
benefits.
Enable JavaScript and CSS Asset Management
------------------------------------------
See :doc:`js_css_asset_management_configuration` for a description and the
benefits.
.. _caching:
Caching
@ -73,3 +67,27 @@ AES-NI extension:
* If your environment runs virtualized, check the virtualization vendor for
support.
Enable HTTP2 for faster loading
-------------------------------
HTTP2 has `huge speed improvements <https://www.troyhunt.com/i-wanna-go-fast-https-massive-speed-advantage/>`_ over HTTP with multiple request. Most `browsers already support HTTP2 over SSL (HTTPS) <http://caniuse.com/#feat=http2>`_. So refer to your server manual for guides on how to use HTTP2.
.. _opcache:
Enable PHP OPcache
------------------
The `OPcache <http://php.net/manual/en/intro.opcache.php>`_ improves the performance of PHP applications by caching precompiled bytecode. We recommend at least following settings:
.. code:: ini
opcache.enable=On
opcache.enable_cli=1
opcache.interned_strings_buffer=8
opcache.max_accelerated_files=10000
opcache.memory_consumption=128
opcache.save_comments=1
opcache.revalidate_freq=1
For more details check out the `official documentation <http://php.net/manual/en/opcache.configuration.php>`_ or `this blog post about some recommended settings <https://www.scalingphpbook.com/blog/2014/02/14/best-zend-opcache-settings.html>`_.

69
admin_manual/configuration_server/sso_configuration.rst Normal file
View File

@ -0,0 +1,69 @@
==========================
Configuring Single-Sign-On
==========================
Using the SSO & SAML app of your Nextcloud you can make it easily possible to integrate your existing Single-Sign-On
solution with Nextcloud. In addition, you can use the Nextcloud LDAP user provider to keep the convenience for users. (e.g.
when sharing)
The following providers are supported and tested at the moment:
- SAML 2.0
- OneLogin
- Shibboleth
- Active Directory Federation Services (ADFS)
- Authentication via Environment Variable
- Kerberos (mod_auth_kerb)
- Any other provider that authenticates using the environment variable
While theoretically any other authentication provider implementing either one of those standards is compatible, we like
to note that they are not part of any internal test matrix.
Enabling the SSO & SAML app
---------------------------
.. warning:: Make sure to configure an administrative user that can access the instance via SSO. Logging-in with your
regular Nextcloud account won't be possible anymore.
The "SSO & SAML" App is shipped and disabled by default. To enable the app enabled simply go to your Nextcloud Apps page
to enable it. It can then be found in the "SSO & SAML authentication" section of your Nextcloud.
Configuring SAML 2.0
--------------------
To configure using SAML choose the "SAML authentication" in the setup wizard of the application. Then configure the application
as required by your Service Provider.
.. figure:: ./images/saml_app_overview.png
Configuring environment based authentication
--------------------------------------------
It is possible to authenticate against Nextcloud using an environment variable. This is for example relevant in case you
use an service provider incompatible with SAML such as Kerberos or don't want to configure SAML in the software yourself.
To enable that choose the "Environment variable" authentication provider in the application and then specify the environment
variable. (e.g. `REMOTE_USER` for Kerberos)
Once done you also need to protect the login route properly. On an Apache server with mod_auth_kerb the following configuration
would protect the login route:
.. code-block:: apache
<Location "/index.php/login">
AuthType Kerberos
AuthName "Kerberos Login"
KrbServiceName HTTP
KrbMethodNegotiate On
KrbMethodK5Passwd Off
KrbSaveCredentials Off
KrbVerifyKDC On
KrbAuthRealms NEXTCLOUD-AD.LOCAL
Krb5KeyTab /etc/apache2/webpage.HTTP.keytab
Require valid-user
</Location>
.. warning:: If this authentication approach is used clients do require an application specific password for authentication.
A better integration into our desktop and mobile clients is considered for the future though.

12
admin_manual/configuration_server/theming.rst
View File

@ -18,3 +18,15 @@ In the administrative settings you can modify the appearance of Nextcloud:
Log in page
.. figure:: ../configuration_server/images/theming-log-in-page.png
Theming of icons
================
Nextcloud will automatically generate favicons and home screen icons
depending on the current app and theming color.
This requires the following additional dependencies:
- PHP module imagick
- SVG support for imagick (e.g. `libmagickcore5-extra`)

1
admin_manual/configuration_user/index.rst
View File

@ -9,6 +9,7 @@ User Management
reset_admin_password
reset_user_password
user_password_policy
two_factor-auth
user_auth_ftp_smb_imap
user_auth_ldap
user_auth_ldap_cleanup

23
admin_manual/configuration_user/two_factor-auth.rst Normal file
View File

@ -0,0 +1,23 @@
=========================
Two Factor Authentication
=========================
Starting with Nextcloud 10, it is possible to use two factor authentication
(2FA) with Nextcloud. It is a plugin based system requiring a 2FA app.
Several 2FA apps are already available including
`TOTP <https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm>`_,
SMS 2-factor and `U2F <https://en.wikipedia.org/wiki/Universal_2nd_Factor>`_.
Developers can `built new two-factor provider apps <https://docs.nextcloud.com/server/11/developer_manual/app/two-factor-provider.html>`_.
.. TODO ON RELEASE: Update version number above on release
Enabling Two Factor Authentication
==================================
You can enable 2FA by installing and enabling a 2FA app like TOTP which works
with Google Authenticator and compatible apps. The apps are available in the
Nextcloud App store so by navigating there and clicking **enable** for the app
you want, 2FA will be installed and enabled on your Nextcloud server.
.. figure:: ../images/2fa-app-install.png
Once 2FA has been enabled, users have to `activate it in their personal settings. <https://docs.nextcloud.com/server/11/user_manual/user_2fa.html>`_
.. TODO ON RELEASE: Update version number above on release

372
admin_manual/configuration_user/user_auth_ldap.rst
View File

@ -2,15 +2,15 @@
User Authentication with LDAP
=============================
Nextcloud ships with an LDAP application to allow LDAP users (including Active
Directory) to appear in your Nextcloud user listings. These users will
authenticate to Nextcloud with their LDAP credentials, so you don't have to
create separate Nextcloud user accounts for them. You will manage their Nextcloud
group memberships, quotas, and sharing permissions just like any other Nextcloud
Nextcloud ships with an LDAP application to allow LDAP users (including Active
Directory) to appear in your Nextcloud user listings. These users will
authenticate to Nextcloud with their LDAP credentials, so you don't have to
create separate Nextcloud user accounts for them. You will manage their Nextcloud
group memberships, quotas, and sharing permissions just like any other Nextcloud
user.
.. note:: The PHP LDAP module is required; this is supplied by ``php5-ldap`` on
Debian/Ubuntu, and ``php-ldap`` on CentOS/Red Hat/Fedora. PHP 5.4+ is
.. note:: The PHP LDAP module is required; this is supplied by ``php5-ldap`` on
Debian/Ubuntu, and ``php-ldap`` on CentOS/Red Hat/Fedora. PHP 5.6+ is
required in Nextcloud.
The LDAP application supports:
@ -19,15 +19,15 @@ The LDAP application supports:
* File sharing with Nextcloud users and groups
* Access via WebDAV and Nextcloud Desktop Client
* Versioning, external Storage and all other Nextcloud features
* Seamless connectivity to Active Directory, with no extra configuration
* Seamless connectivity to Active Directory, with no extra configuration
required
* Support for primary groups in Active Directory
* Auto-detection of LDAP attributes such as base DN, email, and the LDAP server
* Auto-detection of LDAP attributes such as base DN, email, and the LDAP server
port number
* Only read access to your LDAP (edit or delete of users on your LDAP is not
* Only read access to your LDAP (edit or delete of users on your LDAP is not
supported)
.. warning:: The LDAP app is not compatible with the ``User backend using remote
.. warning:: The LDAP app is not compatible with the ``User backend using remote
HTTP servers`` app. You cannot use both of them at the same time.
.. note:: A non-blocking or correctly configured SELinux setup is needed
@ -36,34 +36,34 @@ The LDAP application supports:
Configuration
-------------
First enable the ``LDAP user and group backend`` app on the Apps page in
First enable the ``LDAP user and group backend`` app on the Apps page in
Nextcloud. Then go to your Admin page to configure it.
The LDAP configuration panel has four tabs. A correctly completed first tab
("Server") is mandatory to access the other tabs. A green indicator lights when
the configuration is correct. Hover your cursor over the fields to see some
pop-up tooltips.
The LDAP configuration panel has four tabs. A correctly completed first tab
("Server") is mandatory to access the other tabs. A green indicator lights when
the configuration is correct. Hover your cursor over the fields to see some
pop-up tooltips.
Server Tab
^^^^^^^^^^
Start with the Server tab. You may configure multiple servers if you have them.
At a minimum you must supply the LDAP server's hostname. If your server requires
authentication, enter your credentials on this tab. Nextcloud will then attempt
to auto-detect the server's port and base DN. The base DN and port are
Start with the Server tab. You may configure multiple servers if you have them.
At a minimum you must supply the LDAP server's hostname. If your server requires
authentication, enter your credentials on this tab. Nextcloud will then attempt
to auto-detect the server's port and base DN. The base DN and port are
mandatory, so if Nextcloud cannot detect them you must enter them manually.
.. figure:: ../images/ldap-wizard-1-server.png
:alt: LDAP wizard, server tab
Server configuration:
Configure one or more LDAP servers. Click the **Delete Configuration**
Configure one or more LDAP servers. Click the **Delete Configuration**
button to remove the active configuration.
Host:
The host name or IP address of the LDAP server. It can also be a **ldaps://**
The host name or IP address of the LDAP server. It can also be a **ldaps://**
URI. If you enter the port number, it speeds up server detection.
Examples:
* *directory.my-company.com*
@ -72,9 +72,9 @@ Host:
Port:
The port on which to connect to the LDAP server. The field is disabled in the
beginning of a new configuration. If the LDAP server is running on a standard
port, the port will be detected automatically. If you are using a
non-standard port, Nextcloud will attempt to detect it. If this fails you must
beginning of a new configuration. If the LDAP server is running on a standard
port, the port will be detected automatically. If you are using a
non-standard port, Nextcloud will attempt to detect it. If this fails you must
enter the port number manually.
Example:
@ -82,8 +82,8 @@ Port:
* *389*
User DN:
The name as DN of a user who has permissions to do searches in the LDAP
directory. Leave it empty for anonymous access. We recommend that you have a
The name as DN of a user who has permissions to do searches in the LDAP
directory. Leave it empty for anonymous access. We recommend that you have a
special LDAP system user for this.
Example:
@ -94,46 +94,45 @@ Password:
The password for the user given above. Empty for anonymous access.
Base DN:
The base DN of LDAP, from where all users and groups can be reached. You may
enter multiple base DNs, one per line. (Base DNs for users and groups can be
set in the Advanced tab.) This field is mandatory. Nextcloud attempts to
determine the Base DN according to the provided User DN or the provided
The base DN of LDAP, from where all users and groups can be reached. You may
enter multiple base DNs, one per line. (Base DNs for users and groups can be
set in the Advanced tab.) This field is mandatory. Nextcloud attempts to
determine the Base DN according to the provided User DN or the provided
Host, and you must enter it manually if Nextcloud does not detect it.
Example:
* *dc=my-company,dc=com*
User Filter
^^^^^^^^^^^
Users Tab
^^^^^^^^^
Use this to control which LDAP users are listed as Nextcloud users on your
Nextcloud server. In order to control which LDAP users can login to your Nextcloud
server use the Login filter. Those LDAP users who have access but are not listed
as users (if there are any) will be hidden users. You may bypass the form fields
Use this to control which LDAP users are listed as Nextcloud users on your
Nextcloud server. In order to control which LDAP users can login to your Nextcloud
server use the **Login Attributes** tab. Those LDAP users who have access but are not listed
as users (if there are any) will be hidden users. You may bypass the form fields
and enter a raw LDAP filter if you prefer.
.. figure:: ../images/ldap-wizard-2-user.png
:alt: User filter
only those object classes:
Only those object classes:
Nextcloud will determine the object classes that are typically available for
user objects in your LDAP. Nextcloud will automatically select the object
class that returns the highest amount of users. You may select multiple
user objects in your LDAP. Nextcloud will automatically select the object
class that returns the highest amount of users. You may select multiple
object classes.
only from those groups:
If your LDAP server supports the ``member-of-overlay`` in LDAP filters, you
Only from those groups:
If your LDAP server supports the ``member-of-overlay`` in LDAP filters, you
can define that only users from one or more certain groups are allowed to
appear in user listings in Nextcloud. By default, no value will be selected.
You
may select multiple groups.
appear in user listings in Nextcloud. By default, no value will be selected.
You may select multiple groups.
If your LDAP server does not support the member-of-overlay in LDAP filters,
If your LDAP server does not support the ``member-of-overlay`` in LDAP filters,
the input field is disabled. Please contact your LDAP administrator.
Edit raw filter instead:
Clicking on this text toggles the filter mode and you can enter the raw LDAP
Edit LDAP Query:
Clicking on this text toggles the filter mode and you can enter the raw LDAP
filter directly. Example::
(&(objectClass=inetOrgPerson)(memberOf=cn=nextcloudusers,ou=groups,
@ -143,16 +142,16 @@ x users found:
This is an indicator that tells you approximately how many users will be
listed in Nextcloud. The number updates automatically after any changes.
Login Filter
^^^^^^^^^^^^
Login Attributes Tab
^^^^^^^^^^^^^^^^^^^^
The settings in the Login Filter tab determine which LDAP users can log in to
your Nextcloud system and which attribute or attributes the provided login name
is matched against (e.g. LDAP/AD username, email address). You may select
multiple user details. (You may bypass the form fields and enter a raw LDAP
The settings in the Login Attributes tab determine which LDAP users can log in to
your Nextcloud system and which attribute or attributes the provided login name
is matched against (e.g. LDAP/AD username, email address). You may select
multiple user details. (You may bypass the form fields and enter a raw LDAP
filter if you prefer.)
You may override your User Filter settings on the User Filter tab by using a raw
You may override your User Filter settings on the Users tab by using a raw
LDAP filter.
.. figure:: ../images/ldap-wizard-3-login.png
@ -165,56 +164,56 @@ LDAP Username:
LDAP Email Address:
If this value is checked, the login value will be compared to an email address
in the LDAP directory; specifically, the *mailPrimaryAddress* and *mail*
in the LDAP directory; specifically, the *mailPrimaryAddress* and *mail*
attributes.
Other Attributes:
This multi-select box allows you to select other attributes for the
comparison. The list is generated automatically from the user object
This multi-select box allows you to select other attributes for the
comparison. The list is generated automatically from the user object
attributes in your LDAP server.
Edit raw filter instead:
Clicking on this text toggles the filter mode and you can enter the raw LDAP
Edit LDAP Query:
Clicking on this text toggles the filter mode and you can enter the raw LDAP
filter directly.
The **%uid** placeholder is replaced with the login name entered by the
The **%uid** placeholder is replaced with the login name entered by the
user upon login.
Examples:
* only username::
* only username::
(&(objectClass=inetOrgPerson)(memberOf=cn=nextcloudusers,ou=groups,
dc=example,dc=com)(uid=%uid)
* username or email address::
((&(objectClass=inetOrgPerson)(memberOf=cn=nextcloudusers,ou=groups,
dc=example,dc=com)(|(uid=%uid)(mail=%uid)))
Group Filter
^^^^^^^^^^^^
Groups Tab
^^^^^^^^^^
By default, no LDAP groups will be available in Nextcloud. The settings in the
group filter tab determine which groups will be available in Nextcloud. You may
By default, no LDAP groups will be available in Nextcloud. The settings in the
Groups tab determine which groups will be available in Nextcloud. You may
also elect to enter a raw LDAP filter instead.
.. figure:: ../images/ldap-wizard-4-group.png
:alt: Group filter
only those object classes:
Only these object classes:
Nextcloud will determine the object classes that are typically available for
group objects in your LDAP server. Nextcloud will only list object
classes that return at least one group object. You can select multiple
object classes. A typical object class is "group", or "posixGroup".
only from those groups:
Nextcloud will generate a list of available groups found in your LDAP server.
and then you select the group or groups that get access to your Nextcloud
Only from these groups:
Nextcloud will generate a list of available groups found in your LDAP server.
Then you select the group or groups that get access to your Nextcloud
server.
Edit raw filter instead:
Clicking on this text toggles the filter mode and you can enter the raw LDAP
Edit LDAP Query:
Clicking on this text toggles the filter mode and you can enter the raw LDAP
filter directly.
Example:
@ -223,16 +222,16 @@ Edit raw filter instead:
* *objectClass=posixGroup*
y groups found:
This tells you approximately how many groups will be available in Nextcloud.
This tells you approximately how many groups will be available in Nextcloud.
The number updates automatically after any change.
Advanced Settings
-----------------
The LDAP Advanced Setting section contains options that are not needed for a
working connection. This provides controls to disable the current
configuration,
The LDAP Advanced Setting section contains options that are not needed for a
working connection. This provides controls to disable the current
configuration,
configure replica hosts, and various performance-enhancing options.
The Advanced Settings are structured into three parts:
@ -248,14 +247,14 @@ Connection Settings
:alt: Advanced settings
Configuration Active:
Enables or Disables the current configuration. By default, it is turned off.
When Nextcloud makes a successful test connection it is automatically turned
Enables or Disables the current configuration. By default, it is turned off.
When Nextcloud makes a successful test connection it is automatically turned
on.
Backup (Replica) Host:
If you have a backup LDAP server, enter the connection settings here.
Nextcloud will then automatically connect to the backup when the main server
cannot be reached. The backup server must be a replica of the main server so
If you have a backup LDAP server, enter the connection settings here.
Nextcloud will then automatically connect to the backup when the main server
cannot be reached. The backup server must be a replica of the main server so
that the object UUIDs match.
Example:
@ -278,27 +277,27 @@ Turn off SSL certificate validation:
Turns off SSL certificate checking. Use it for testing only!
Cache Time-To-Live:
A cache is introduced to avoid unnecessary LDAP traffic, for example caching
usernames so they don't have to be looked up for every page, and speeding up
loading of the Users page. Saving the configuration empties the cache. The
A cache is introduced to avoid unnecessary LDAP traffic, for example caching
usernames so they don't have to be looked up for every page, and speeding up
loading of the Users page. Saving the configuration empties the cache. The
time is given in seconds.
Note that almost every PHP request requires a new connection to the LDAP
server. If you require fresh PHP requests we recommend defining a minimum
Note that almost every PHP request requires a new connection to the LDAP
server. If you require fresh PHP requests we recommend defining a minimum
lifetime of 15s or so, rather than completely eliminating the cache.
Examples:
* ten minutes: *600*
* one hour: *3600*
See the Caching section below for detailed information on how the cache
See the Caching section below for detailed information on how the cache
operates.
.. _ldap_directory_settings:
Directory Settings
^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^
.. figure:: ../images/ldap-advanced-2-directory.png
:alt: Directory settings.
@ -307,15 +306,15 @@ User Display Name Field:
The attribute that should be used as display name in Nextcloud.
* Example: *displayName*
2nd User Display Name Field:
An optional second attribute displayed in brackets after the display name,
for example using the ``mail`` attribute displays as ``Molly Foo
2nd User Display Name Field:
An optional second attribute displayed in brackets after the display name,
for example using the ``mail`` attribute displays as ``Molly Foo
(molly@example.com)``.
Base User Tree:
The base DN of LDAP, from where all users can be reached. This must be a
complete DN, regardless of what you have entered for your Base DN in the
The base DN of LDAP, from where all users can be reached. This must be a
complete DN, regardless of what you have entered for your Base DN in the
Basic setting. You can specify multiple base trees, one on each line.
* Example:
@ -324,13 +323,13 @@ Base User Tree:
| *cn=designers,dc=my-company,dc=com*
User Search Attributes:
These attributes are used when searches for users are performed, for example
in the share dialogue. The user display name attribute is the
These attributes are used when searches for users are performed, for example
in the share dialogue. The user display name attribute is the
default. You may list multiple attributes, one per line.
If an attribute is not available on a user object, the user will not be
listed, and will be unable to login. This also affects the display name
attribute. If you override the default you must specify the display name
If an attribute is not available on a user object, the user will not be
listed, and will be unable to login. This also affects the display name
attribute. If you override the default you must specify the display name
attribute here.
* Example:
@ -340,14 +339,14 @@ User Search Attributes:
Group Display Name Field:
The attribute that should be used as Nextcloud group name. Nextcloud allows a
limited set of characters (a-zA-Z0-9.-_@). Once a group name is assigned it
limited set of characters (a-zA-Z0-9.-_@). Once a group name is assigned it
cannot be changed.
* Example: *cn*
Base Group Tree:
The base DN of LDAP, from where all groups can be reached. This must be a
complete DN, regardless of what you have entered for your Base DN in the
The base DN of LDAP, from where all groups can be reached. This must be a
complete DN, regardless of what you have entered for your Base DN in the
Basic setting. You can specify multiple base trees, one in each line.
* Example:
@ -356,8 +355,8 @@ Base Group Tree:
| *cn=madrid,dc=my-company,dc=com*
Group Search Attributes:
These attributes are used when a search for groups is done, for example in
the share dialogue. By default the group display name attribute as specified
These attributes are used when a search for groups is done, for example in
the share dialogue. By default the group display name attribute as specified
above is used. Multiple attributes can be given, one in each line.
If you override the default, the group display name attribute will not be
@ -384,17 +383,14 @@ Enable LDAP password changes per user:
* General requirements:
| - Access control policies must be configured on the LDAP server to grant permissions for password changes.
|
| - Passwords are sent in plaintext to the LDAP server. Therefore, transport encryption must be used for the communication between Nextcloud and the LDAP server, e.g. employ LDAPS.
|
| - Enabling password hashing on the LDAP server is highly recommended. While Active Directory stores passwords in a one-way format by default, OpenLDAP users could configure the ``ppolicy_hash_cleartext`` directive of the ppolicy overlay that ships with OpenLDAP.
* Access control policies must be configured on the LDAP server to grant permissions for password changes.
* Passwords are sent in plaintext to the LDAP server. Therefore, transport encryption must be used for the communication between Nextcloud and the LDAP server, e.g. employ LDAPS.
* Enabling password hashing on the LDAP server is highly recommended. While Active Directory stores passwords in a one-way format by default, OpenLDAP users could configure the ``ppolicy_hash_cleartext`` directive of the ppolicy overlay that ships with OpenLDAP.
* Additional requirements for Active Directory:
| - At least a 128-bit transport encryption must be used for the communication between Nextcloud and the LDAP server.
|
| - Make sure that the ``fUserPwdSupport`` char of the dSHeuristics is configured to employ the ``userPassword`` attribute as ``unicodePwd`` alias. While this is set accordingly on AD LDS by default, this is not the case on AD DS.
* At least a 128-bit transport encryption must be used for the communication between Nextcloud and the LDAP server.
* Make sure that the ``fUserPwdSupport`` char of the dSHeuristics is configured to employ the ``userPassword`` attribute as ``unicodePwd`` alias. While this is set accordingly on AD LDS by default, this is not the case on AD DS.
Default password policy DN:
The DN of a default password policy that will be used for password expiry handling in the absence of any user specific password policy. Password expiry handling features the following:
@ -420,38 +416,38 @@ Special Attributes
Quota Field:
Nextcloud can read an LDAP attribute and set the user quota according to its
value. Specify the attribute here, and it will return human-readable values,
e.g. "2 GB". Any quota set in LDAP overrides quotas set on the Nextcloud user
value. Specify the attribute here, and it will return human-readable values,
e.g. "2 GB". Any quota set in LDAP overrides quotas set on the Nextcloud user
management page.
* Example: *NextcloudQuota*
Quota Default:
Override Nextcloud default quota for LDAP users who do not have a quota set in
Override Nextcloud default quota for LDAP users who do not have a quota set in
the Quota Field.
* Example: *15 GB*
Email Field:
Set the user's email from their LDAP attribute. Leave it empty for default
Set the user's email from their LDAP attribute. Leave it empty for default
behavior.
* Example: *mail*
User Home Folder Naming Rule:
By default, the Nextcloud server creates the user directory in your Nextcloud
By default, the Nextcloud server creates the user directory in your Nextcloud
data directory and gives it the Nextcloud username, .e.g ``/var/www/nextcloud/data/alice``. You may want to override this setting and name it after an LDAP
attribute value. The attribute can also return an absolute path, e.g.
attribute value. The attribute can also return an absolute path, e.g.
``/mnt/storage43/alice``. Leave it empty for default behavior.
* Example: *cn*
In new Nextcloud installations the home folder rule is enforced. This means that once you set a home folder naming rule (get a home folder from an LDAP attribute), it must be available for all users. If it isn't available for a user, then that user will not be able to login. Also, the filesystem will not be set up for that user, so their file shares will not be available to other users.
In migrated Nextcloud installations the old behavior still applies, which is using the Nextcloud username as the home folder when an LDAP attribute is not set. You may change this to enforcing the home folder rule with the ``occ`` command in Nextcloud, like this example on Ubuntu::
In migrated Nextcloud installations the old behavior still applies, which is using the Nextcloud username as the home folder when an LDAP attribute is not set. You may change this enforcing the home folder rule with the ``occ`` command in Nextcloud, like this example on Ubuntu::
sudo -u www-data php occ config:app:set user_ldap enforce_home_folder_naming_rule --value=1
sudo -u www-data php occ config:app:set user_ldap enforce_home_folder_naming_rule --value=1
Expert Settings
---------------
@ -463,9 +459,9 @@ configuration should be well-tested before starting production use.
Internal Username:
The internal username is the identifier in Nextcloud for LDAP users. By default
it will be created from the UUID attribute. The UUID attribute ensures that
the username is unique, and that characters do not need to be converted. Only
these characters are allowed: [\a-\zA-\Z0-\9_.@-]. Other characters are
it will be created from the UUID attribute. The UUID attribute ensures that
the username is unique, and that characters do not need to be converted. Only
these characters are allowed: [\a-\zA-\Z0-\9_.@-]. Other characters are
replaced with their ASCII equivalents, or are simply omitted.
The LDAP backend ensures that there are no duplicate internal usernames in
@ -474,26 +470,26 @@ Internal Username:
and 9999) will be attached to the retrieved value. For example, if "alice"
exists, the next username may be "alice_1337".
The internal username is the default name for the user home folder in
Nextcloud. It is also a part of remote URLs, for instance for all \*DAV
The internal username is the default name for the user home folder in
Nextcloud. It is also a part of remote URLs, for instance for all \*DAV
services.
You can override all of this with the Internal Username setting. Leave it
You can override all of this with the Internal Username setting. Leave it
empty for default behaviour. Changes will affect only newly mapped LDAP users.
* Example: *uid*
Override UUID detection
By default, Nextcloud auto-detects the UUID attribute. The UUID attribute is
used to uniquely identify LDAP users and groups. The internal username will
used to uniquely identify LDAP users and groups. The internal username will
be created based on the UUID, if not specified otherwise.
You can override the setting and pass an attribute of your choice. You must
make sure that the attribute of your choice can be fetched for both users and
groups and it is unique. Leave it empty for default behaviour. Changes will
have effect only on newly mapped LDAP users and groups. It also will
have effect when a user's or group's DN changes and an old UUID was cached,
which will result in a new user. Because of this, the setting should be
have effect when a user's or group's DN changes and an old UUID was cached,
which will result in a new user. Because of this, the setting should be
applied before putting Nextcloud in production use and clearing the bindings
(see the ``User and Group Mapping`` section below).
@ -511,78 +507,73 @@ Username-LDAP User Mapping
The same is valid for groups.
The internal Nextcloud name is used all over in Nextcloud. Clearing the Mappings
will have leftovers everywhere. Never clear the mappings in a production
will have leftovers everywhere. Never clear the mappings in a production
environment, but only in a testing or experimental server.
**Clearing the Mappings is not configuration sensitive, it affects all LDAP
configurations!**
.. warning:: Clearing the Mappings is not configuration sensitive, it affects all LDAP
configurations!
Testing the configuration
-------------------------
The **Test Configuration** button checks the values as currently given in the
input fields. You do not need to save before testing. By clicking on the
The **Test Configuration** button checks the values as currently given in the
input fields. You do not need to save before testing. By clicking on the
button, Nextcloud will try to bind to the Nextcloud server using the
settings currently given in the input fields. If the binding fails you'll see a
yellow banner with the error message "The configuration is invalid. Please have
a look at the logs for further details."
settings currently given in the input fields. If the binding fails you'll see a
yellow banner with the error message "The configuration is invalid. Please have
a look at the logs for further details."
When the configuration test reports success, save your settings and check if the
When the configuration test reports success, save your settings and check if the
users and groups are fetched correctly on the Users page.
Nextcloud Avatar integration
----------------------------
Nextcloud supports user profile pictures, which are also called avatars. If a user
has a photo stored in the *jpegPhoto* or *thumbnailPhoto* attribute on your LDAP
server, it will be used as their avatar. In this case the user cannot alter their
avatar (on their Personal page) as it must be changed in LDAP. *jpegPhoto* is
Nextcloud supports user profile pictures, which are also called avatars. If a user
has a photo stored in the *jpegPhoto* or *thumbnailPhoto* attribute on your LDAP
server, it will be used as their avatar. In this case the user cannot alter their
avatar (on their Personal page) as it must be changed in LDAP. *jpegPhoto* is
preferred over *thumbnailPhoto*.
.. figure:: ../images/ldap-fetched-avatar.png
:alt: Profile picture fetched from LDAP.
If the *jpegPhoto* or *thumbnailPhoto* attribute is not set or empty, then
users can upload and manage their avatars on their Nextcloud Personal pages.
If the *jpegPhoto* or *thumbnailPhoto* attribute is not set or empty, then
users can upload and manage their avatars on their Nextcloud Personal pages.
Avatars managed in Nextcloud are not stored in LDAP.
The *jpegPhoto* or *thumbnailPhoto* attribute is fetched once a day to make
sure the current photo from LDAP is used in Nextcloud. LDAP avatars override
Nextcloud avatars, and when an LDAP avatar is deleted then the most recent
sure the current photo from LDAP is used in Nextcloud. LDAP avatars override
Nextcloud avatars, and when an LDAP avatar is deleted then the most recent
Nextcloud avatar replaces it.
Photos served from LDAP are automatically cropped and resized in Nextcloud. This
Photos served from LDAP are automatically cropped and resized in Nextcloud. This
affects only the presentation, and the original image is not changed.
Troubleshooting, Tips and Tricks
--------------------------------
SSL Certificate Verification (LDAPS, TLS)
-----------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A common mistake with SSL certificates is that they may not be known to PHP.
If you have trouble with certificate validation make sure that
* You have the certificate of the server installed on the Nextcloud server
* The certificate is announced in the system's LDAP configuration file (usually
*/etc/ldap/ldap.conf*
.. commenting out windows section as windows server is not supported
.. *C:\\openldap\\sysconf\\ldap.conf* or
.. *C:\\ldap.conf* on Windows) using a **TLS_CACERT /path/to/cert** line.
*/etc/ldap/ldap.conf*)
* Using LDAPS, also make sure that the port is correctly configured (by default
636)
Microsoft Active Directory
--------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^
Compared to earlier Nextcloud versions, no further tweaks need to be done to
make Nextcloud work with Active Directory. Nextcloud will automatically find the
correct configuration in the set-up process.
memberOf / Read MemberOf permissions
------------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If you want to use ``memberOf`` within your filter you might need to give your
querying user the permissions to use it. For Microsoft Active Directory this
@ -590,7 +581,7 @@ is described `here <https://serverfault.com/questions/167371/what-permissions-ar
-required-for-enumerating-users-groups-in-active-directory/167401#167401>`_.
Duplicating Server Configurations
---------------------------------
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In case you have a working configuration and want to create a similar one or
"snapshot" configurations before modifying them you can do the following:
@ -605,6 +596,22 @@ In case you have a working configuration and want to create a similar one or
Now you can modify and enable the configuration.
"Sizelimit exceeded" message in logs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ldap_search(): Partial search results returned: Sizelimit exceeded at
apps/user_ldap/lib/LDAP.php#256
This error message means one of the following:
#. Pagination of the results is used for communicating with the LDAP server
(pagination is by default enabled in OpenLDAP and AD), but there are more
results to return than what the pagination limit is set to. If there are no
users missing in you setup then you can ignore this error message for now.
#. No pagination is used and this indicates that there are more results on the
LDAP server than what is returned. You should then enabled pagination on
your LDAP server to import all available users.
Nextcloud LDAP Internals
------------------------
@ -634,43 +641,42 @@ Caching
^^^^^^^
The LDAP information is cached in Nextcloud memory cache, and you must install
and configure the memory cache (see
and configure the memory cache (see
:doc:`../configuration_server/caching_configuration`). The Nextcloud **Cache**
helps to speed up user interactions and sharing. It is populated on demand,
and remains populated until the **Cache Time-To-Live** for each unique request
expires. User logins are not cached, so if you need to improve login times set
up a slave LDAP server to share the load.
You can adjust the **Cache Time-To-Live** value to balance performance and
freshness of LDAP data. All LDAP requests will be cached for 10 minutes by
default, and you can alter this with the **Cache Time-To-Live** setting. The
cache answers each request that is identical to a previous request, within the
You can adjust the **Cache Time-To-Live** value to balance performance and
freshness of LDAP data. All LDAP requests will be cached for 10 minutes by
default, and you can alter this with the **Cache Time-To-Live** setting. The
cache answers each request that is identical to a previous request, within the
time-to-live of the original request, rather than hitting the LDAP server.
The **Cache Time-To-Live** is related to each single request. After a cache
entry expires there is no automatic trigger for re-populating the information,
as the cache is populated only by new requests, for example by opening the
The **Cache Time-To-Live** is related to each single request. After a cache
entry expires there is no automatic trigger for re-populating the information,
as the cache is populated only by new requests, for example by opening the
User administration page, or searching in a sharing dialog.
There is one trigger which is automatically triggered by a certain background
There is one trigger which is automatically triggered by a certain background
job which keeps the ``user-group-mappings`` up-to-date, and always in cache.
Under normal circumstances, all users are never loaded at the same time.
Typically the loading of users happens while page results are generated, in
steps of 30 until the limit is reached or no results are left. For this to
work on an oC-Server and LDAP-Server, **Paged Results** must be supported,
which presumes PHP >= 5.4.
Under normal circumstances, all users are never loaded at the same time.
Typically the loading of users happens while page results are generated, in
steps of 30 until the limit is reached or no results are left. For this to
work on an oC-Server and LDAP-Server, **Paged Results** must be supported.
Nextcloud remembers which user belongs to which LDAP-configuration. That means
each request will always be directed to the right server unless a user is
defunct, for example due to a server migration or unreachable server. In this
Nextcloud remembers which user belongs to which LDAP-configuration. That means
each request will always be directed to the right server unless a user is
defunct, for example due to a server migration or unreachable server. In this
case the other servers will also receive the request.
Handling with Backup Server
^^^^^^^^^^^^^^^^^^^^^^^^^^^
When Nextcloud is not able to contact the main LDAP server, Nextcloud assumes it
is offline and will not try to connect again for the time specified in **Cache
Time-To-Live**. If you have a backup server configured Nextcloud will connect to
it instead. When you have scheduled downtime, check **Disable Main Server** to
When Nextcloud is not able to contact the main LDAP server, Nextcloud assumes it
is offline and will not try to connect again for the time specified in **Cache
Time-To-Live**. If you have a backup server configured Nextcloud will connect to
it instead. When you have scheduled downtime, check **Disable Main Server** to
avoid unnecessary connection attempts.

274
admin_manual/configuration_user/user_provisioning_api.rst
View File

@ -13,11 +13,15 @@ listed above. The Provisioning API app is enabled by default.
The base URL for all calls to the share API is **nextcloud_base_url/ocs/v1.php/cloud**.
All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``.
All POST requests require the ``Content-Type: application/x-www-form-urlencoded`` header. (Note: Some libraries like Curl set this header automatically, other require to set the header explicitly)
Instruction Set For Users
=========================
**users / adduser**
-------------------
Add a new user
--------------
Create a new user on the Nextcloud server. Authentication is done by sending a
basic HTTP authentication header.
@ -45,7 +49,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -57,8 +61,8 @@ XML Output
<data/>
</ocs>
**users / getusers**
--------------------
Search/get users
----------------
Retrieves a list of users from the Nextcloud server. Authentication is done by
sending a Basic HTTP Authorization header.
@ -83,7 +87,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -98,8 +102,8 @@ XML Output
</data>
</ocs>
**users / getuser**
-------------------
Get data of a single user
-------------------------
Retrieves information about a single user. Authentication is done by sending a
Basic HTTP Authorization header.
@ -121,7 +125,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -130,14 +134,24 @@ XML Output
<status>ok</status>
</meta>
<data>
<email>frank@example.org</email>
<quota>0</quota>
<enabled>true</enabled>
<id>Frank</id>
<quota>0</quota>
<email>frank@example.org</email>
<displayname>Frank K.</displayname>
<phone>0123 / 456 789</phone>
<address>Foobar 12, 12345 Town</address>
<website>https://nextcloud.com</website>
<twitter>Nextcloud</twitter>
<groups>
<element>group1</element>
<element>group2</element>
</groups>
</data>
</ocs>
**users / edituser**
--------------------
Edit data of a single user
--------------------------
Edits attributes related to a user. Users are able to edit email, displayname
and password; admins can also edit the quota value. Authentication is done by
@ -146,7 +160,18 @@ sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}**
* HTTP method: PUT
* PUT argument: key, the field to edit (email, quota, display, password)
* PUT argument: key, the field to edit:
+ email
+ quota
+ displayname
+ display (**deprecated** use `displayname` instead)
+ phone
+ address
+ website
+ twitter
+ password
* PUT argument: value, the new value for the field
Status codes:
@ -158,18 +183,18 @@ Status codes:
Examples
^^^^^^^^
* PUT ``PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -d
* PUT ``http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -d
key="email" -d value="franksnewemail@example.org"``
* Updates the email address for the user ``Frank``
* PUT ``PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -d
* PUT ``http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank -d
key="quota" -d value="100MB"``
* Updates the quota for the user ``Frank``
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -180,8 +205,80 @@ XML Output
<data/>
</ocs>
**users / deleteuser**
----------------------
Disable a user
--------------
Disables a user on the Nextcloud server so that the user cannot login anymore.
Authentication is done by sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}/disable**
* HTTP method: PUT
Statuscodes:
* 100 - successful
* 101 - failure
Example
^^^^^^^
* PUT ``http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/disable``
* Disables the user ``Frank``
XML Output
^^^^^^^^^^
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data/>
</ocs>
Enable a user
-------------
Enables a user on the Nextcloud server so that the user can login again.
Authentication is done by sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}/enable**
* HTTP method: PUT
Statuscodes:
* 100 - successful
* 101 - failure
Example
^^^^^^^
* PUT ``http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/enable``
* Enables the user ``Frank``
XML Output
^^^^^^^^^^
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data/>
</ocs>
Delete a user
-------------
Deletes a user from the Nextcloud server. Authentication is done by sending a
Basic HTTP Authorization header.
@ -204,7 +301,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -215,8 +312,8 @@ XML Output
<data/>
</ocs>
**users / getgroups**
---------------------
Get user´s groups
-----------------
Retrieves a list of groups the specified user is a member of. Authentication is
done by sending a Basic HTTP Authorization header.
@ -238,7 +335,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -254,8 +351,8 @@ XML Output
</data>
</ocs>
**users / addtogroup**
----------------------
Add user to group
-----------------
Adds the specified user to the specified group. Authentication is done by
sending a Basic HTTP Authorization header.
@ -284,7 +381,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -295,8 +392,8 @@ XML Output
<data/>
</ocs>
**users / removefromgroup**
---------------------------
Remove user from group
----------------------
Removes the specified user from the specified group. Authentication is done by
sending a Basic HTTP Authorization header.
@ -304,7 +401,7 @@ sending a Basic HTTP Authorization header.
**Syntax: ocs/v1.php/cloud/users/{userid}/groups**
* HTTP method: DELETE
* POST argument: groupid, string - the group to remove the user from
* DELETE argument: groupid, string - the group to remove the user from
Status codes:
@ -326,7 +423,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -337,8 +434,8 @@ XML Output
<data/>
</ocs>
**users / createsubadmin**
--------------------------
Promote user to subadmin
------------------------
Makes a user the subadmin of a group. Authentication is done by sending a Basic
HTTP Authorization header.
@ -367,7 +464,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -378,8 +475,8 @@ XML Output
<data/>
</ocs>
**users / removesubadmin**
--------------------------
Demote user from subadmin
-------------------------
Removes the subadmin rights for the user specified from the group specified.
Authentication is done by sending a Basic HTTP Authorization header.
@ -408,7 +505,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -419,8 +516,8 @@ XML Output
<data/>
</ocs>
**users / getsubadmingroups**
-----------------------------
Get user´s subadmin groups
--------------------------
Returns the groups in which the user is a subadmin. Authentication is done by
sending a Basic HTTP Authorization header.
@ -445,7 +542,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -458,12 +555,49 @@ XML Output
<element>testgroup</element>
</data>
</ocs>
Resend the welcome email
------------------------
The request to this endpoint triggers the welcome email for this user again.
**Syntax: ocs/v1.php/cloud/users/{userid}/welcome**
* HTTP method: POST
Status codes:
* 100 - successful
* 101 - email address not available
* 102 - sending email failed
Example
^^^^^^^
* POST
``https://admin:secret@example.com/ocs/v1.php/cloud/users/Frank/welcome``
* Sends the welcome email to ``Frank``
XML Output
^^^^^^^^^^
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data/>
</ocs>
Instruction Set For Groups
==========================
**groups / getgroups**
----------------------
Search/get groups
-----------------
Retrieves a list of groups from the Nextcloud server. Authentication is done by
sending a Basic HTTP Authorization header.
@ -488,7 +622,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -503,8 +637,8 @@ XML Output
</data>
</ocs>
**groups / addgroup**
---------------------
Create a group
--------------
Adds a new group. Authentication is done by
sending a Basic HTTP Authorization header.
@ -531,7 +665,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -542,8 +676,8 @@ XML Output
<data/>
</ocs>
**groups / getgroup**
---------------------
Get members of a group
----------------------
Retrieves a list of group members. Authentication is done by sending a Basic
HTTP Authorization header.
@ -565,7 +699,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -580,8 +714,8 @@ XML Output
</data>
</ocs>
**groups / getsubadmins**
-------------------------
Get subadmins of a group
------------------------
Returns subadmins of the group. Authentication is done by
sending a Basic HTTP Authorization header.
@ -606,7 +740,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -620,8 +754,8 @@ XML Output
</data>
</ocs>
**groups / deletegroup**
------------------------
Delete a group
--------------
Removes a group. Authentication is done by
sending a Basic HTTP Authorization header.
@ -645,7 +779,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -655,12 +789,12 @@ XML Output
</meta>
<data/>
</ocs>
Instruction Set For Apps
=========================
**apps / getapps**
------------------
Instruction Set For Apps
========================
Getlist of apps
---------------
Returns a list of apps installed on the Nextcloud server. Authentication is done
by sending a Basic HTTP Authorization
@ -685,7 +819,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -701,8 +835,8 @@ XML Output
</data>
</ocs>
**apps / getappinfo**
---------------------
Get app info
------------
Provides information on a specific application. Authentication is done by
sending a Basic HTTP Authorization header.
@ -724,7 +858,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -755,8 +889,8 @@ XML Output
</data>
</ocs>
**apps / enable**
-----------------
Enable an app
-------------
Enable an app. Authentication is done by sending a Basic HTTP Authorization
header.
@ -778,7 +912,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>
@ -788,8 +922,8 @@ XML Output
</meta>
</ocs>
**apps / disable**
------------------
Disable an app
--------------
Disables the specified app. Authentication is
done by sending a Basic HTTP Authorization header.
@ -812,7 +946,7 @@ Example
XML Output
^^^^^^^^^^
::
.. code-block:: xml
<?xml version="1.0"?>
<ocs>

1
admin_manual/contents.rst
View File

@ -7,7 +7,6 @@ Table of Contents
index
release_notes
whats_new_admin
installation/index
configuration_server/index
configuration_user/index

BIN
admin_manual/images/2fa-app-install.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 52 KiB

BIN
admin_manual/images/antivirus-app.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 7.2 KiB

BIN
admin_manual/images/antivirus-config.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 16 KiB

BIN
admin_manual/images/antivirus-daemon-socket.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 16 KiB

After

Width:  |  Height:  |  Size: 7.1 KiB

BIN
admin_manual/images/antivirus-daemon.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 6.8 KiB

BIN
admin_manual/images/antivirus-executable.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 8.3 KiB

BIN
admin_manual/images/antivirus-logging.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.9 KiB

After

Width:  |  Height:  |  Size: 2.4 KiB

BIN
admin_manual/images/documents_app_enable.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 25 KiB

BIN
admin_manual/images/documents_apply_test.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 20 KiB

BIN
admin_manual/images/ldap-advanced-2-directory.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 76 KiB

After

Width:  |  Height:  |  Size: 28 KiB

32
admin_manual/index.rst
View File

@ -5,31 +5,31 @@ Nextcloud |version| Server Administration Manual Introduction
Introduction
------------
Welcome to the Nextcloud Server Administration Guide. This guide describes
administration tasks for Nextcloud, the flexible open source file synchronization
and sharing solution. Nextcloud includes the Nextcloud server, which runs on
Linux, client applications for Microsoft Windows, Mac OS X and Linux, and mobile
Welcome to the Nextcloud Server Administration Guide. This guide describes
administration tasks for Nextcloud, the flexible open source file synchronization
and sharing solution. Nextcloud includes the Nextcloud server, which runs on
Linux, client applications for Microsoft Windows, Mac OS X and Linux, and mobile
clients for the Android and Apple iOS operating systems.
Current editions of Nextcloud manuals are always available online at
`docs.nextcloud.org <https://docs.nextcloud.org/>`_.
Current editions of Nextcloud manuals are always available online at
`docs.nextcloud.com <https://docs.nextcloud.com/>`_.
Nextcloud server is available:
* As a free, full featured community-supported server, with all enterprise features.
* Or with full enterprise support, including phone and email access to Nextcloud developers.
See :doc:`../whats_new_admin` for more information on the different Nextcloud
See :doc:`../release_notes` for more information on the different Nextcloud
editions.
Nextcloud Videos and Blogs
--------------------------
See the `official Nextcloud channel
<https://www.youtube.com/channel/UCQjN5Fs5QSz1loJqLb5bkew>`_
See the `official Nextcloud channel
<https://www.youtube.com/channel/UCQjN5Fs5QSz1loJqLb5bkew>`_
on YouTube for tutorials, overviews, and conference videos.
Visit `Nextcloud Planet <https://nextcloud.com/news/>`_ for news and developer
Visit `Nextcloud Planet <https://nextcloud.com/news/>`_ for news and developer
blogs.
Target Audience
@ -37,17 +37,17 @@ Target Audience
This guide is for users who want to install, administer, and
optimize their Nextcloud servers. To learn more about the Nextcloud Web
user interface, and desktop and mobile clients, please refer to their
user interface, and desktop and mobile clients, please refer to their
respective manuals:
* `Nextcloud User Manual`_
* `Nextcloud/ownCloud Desktop Client`_
* `Nextcloud Android App`_
* `Nextcloud iOS App`_
* `Nextcloud iOS App`_
.. _`Nextcloud User Manual`: https://docs.nextcloud.org/server/11/user_manual/
.. _`Nextcloud User Manual`: https://docs.nextcloud.com/server/11/user_manual/
.. _`Nextcloud/ownCloud Desktop Client`: https://doc.owncloud.org/desktop/2.2/
.. _`Nextcloud Android App`: https://docs.nextcloud.org/android/
.. _`Nextcloud iOS App`: https://docs.nextcloud.org/ios/
.. _`Nextcloud Android App`: https://docs.nextcloud.com/android/
.. _`Nextcloud iOS App`: https://docs.nextcloud.com/ios/
.. TODO ON RELEASE: Update version number above on release

448
admin_manual/installation/deployment_recommendations.rst
View File

@ -2,36 +2,38 @@
Nextcloud Deployment Recommendations
====================================
What is the best way to install and maintain Nextcloud? The answer to that is
*"it depends"* because every Nextcloud customer has their own
particular needs and IT infrastructure. Nextcloud and the LAMP stack are
highly-configurable, so we will present three typical scenarios and make
What is the best way to install and maintain Nextcloud? The answer to that is
*"it depends"* because every Nextcloud customer has their own
particular needs and IT infrastructure. Nextcloud and the LAMP stack are
highly-configurable, so we will present three typical scenarios and make
best-practice recommendations for both software and hardware.
General Recommendations
-----------------------
.. note:: Whatever the size of your organization, always keep one thing in mind:
.. note:: Whatever the size of your organization, always keep one thing in mind:
the amount of data stored in Nextcloud will only grow. Plan ahead.
Consider setting up a scale-out deployment, or using Federated Cloud Sharing to
Consider setting up a scale-out deployment, or using Federated Cloud Sharing to
keep individual Nextcloud instances to a manageable size.
.. comment: Federating instances seems the best way to grow organically in
an enterprise. A lookup server to tie all the instances together under a
.. comment: Federating instances seems the best way to grow organically in
an enterprise. A lookup server to tie all the instances together under a
single domain is being worked on.
* Operating system: Linux.
* Operating system: Linux (Ubuntu 16.04 or Red Hat Enterprise Linux 7 is recommended).
* Web server: Apache 2.4.
* Database: MySQL/MariaDB.
* PHP 5.5+. PHP 5.4 is the minimum supported version; note that it reached
end-of-life in September 2015 and is no longer supported by the PHP team.
Some Linux vendors, such as Red Hat, still support PHP 5.4.
5.6+ is recommended. ``mod_php`` is the recommended Apache module because it
provides the best performance.
* PHP 5.6+. PHP 5.6 is the minimum supported version. We recommend to deploy
on PHP 7 if possible. This version is known to offer significant performance
advantages. ``mod_php`` is the recommended Apache module due to
vendor support and ease of configuration. ``php-fpm`` with Apache Event
MPM (or nginx) is an alternative with potentially better scalability in
high load and limited RAM environments. For the best results we recommend
working with the Nextcloud GmbH enterprise support team for large deployments.
.. comment: mod_php is easier to set up, php-fpm with apache event MPM seems to
scale better under load and limited RAM restrictions:
.. comment: mod_php is easier to set up, php-fpm with apache event MPM seems to
scale better under load and limited RAM restrictions:
http://blog.bitnami.com/2014/06/performance-enhacements-for-apache-and.html
Small Workgroups or Departments
@ -44,14 +46,14 @@ Small Workgroups or Departments
100 GB to 10TB.
* High availability level
Zero-downtime backups via Btrfs snapshots, component failure leads to
interruption of service. Alternate backup scheme on other filesystems:
Zero-downtime backups via Btrfs snapshots, component failure leads to
interruption of service. Alternate backup scheme on other filesystems:
nightly backups with service interruption.
Recommended System Requirements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
One machine running the application server, Web server, database server and
One machine running the application server, Web server, database server and
local storage.
Authentication via an existing LDAP or Active Directory server.
@ -59,79 +61,79 @@ Authentication via an existing LDAP or Active Directory server.
.. figure:: images/deprecs-1.png
:alt: Network diagram for small enterprises.
.. comment:
https://yuml.me
[web server|DB; local storage]->[LDAP]
* Components
One server with at least 2 CPU cores, 16GB RAM, local storage as needed.
* Operating system
Enterprise-grade Linux distribution with full support from OS vendor. We
recommend Red Hat Enterprise Linux or SUSE Linux Enterprise Server 12.
Enterprise grade Linux distribution with full support from OS vendor. Red
Hat Enterprise Linux or Ubuntu 16.04 are recommended.
* SSL Configuration
The SSL termination is done in Apache. A standard SSL certificate is
The SSL termination is done in Apache. A standard SSL certificate is
needed, installed according to the Apache documentation.
* Load Balancer
None.
None.
* Database
MySQL, MariaDB or PostgreSQL. We currently recommend MySQL / MariaDB, as our
customers have had good experiences when moving to a Galera cluster to
MySQL, MariaDB or PostgreSQL. We currently recommend MySQL / MariaDB, as our
customers have had good experiences when moving to a Galera cluster to
scale the DB.
* Backup
Install Nextcloud, Nextcloud data directory and database on Btrfs filesystem.
Make regular snapshots at desired intervals for zero downtime backups.
Install Nextcloud, Nextcloud data directory and database on Btrfs filesystem.
Make regular snapshots at desired intervals for zero downtime backups.
Mount DB partitions with the "nodatacow" option to prevent fragmentation.
Alternatively, make nightly backups with service interruption:
* Shut down Apache.
* Create database dump.
* Push data directory to backup.
* Push database dump to backup.
* Start Apache.
Then optionally rsync to a backup storage or tape backup. (See the
`Maintenance`_ section of the Administration manual for tips on backups
Then optionally rsync to a backup storage or tape backup. (See the
`Maintenance`_ section of the Administration manual for tips on backups
and restores.)
* Authentication
User authentication via one or several LDAP or Active Directory servers. (See
`User Authentication with LDAP`_ for information on configuring Nextcloud to
`User Authentication with LDAP`_ for information on configuring Nextcloud to
use LDAP and AD.)
* Session Management
Local session management on the application server. PHP sessions are stored
in a tmpfs mounted at the operating system-specific session storage
location. You can find out where that is by running ``grep -R
'session.save_path' /etc/php5`` and then add it to the ``/etc/fstab`` file,
for example:
``echo "tmpfs /var/lib/php5/pool-www tmpfs defaults,noatime,mode=1777 0 0"
Local session management on the application server. PHP sessions are stored
in a tmpfs mounted at the operating system-specific session storage
location. You can find out where that is by running ``grep -R
'session.save_path' /etc/php5`` and then add it to the ``/etc/fstab`` file,
for example:
``echo "tmpfs /var/lib/php5/pool-www tmpfs defaults,noatime,mode=1777 0 0"
>> /etc/fstab``.
* Memory Caching
A memcache speeds up server performance, and Nextcloud supports four
memcaches; refer to `Configuring Memory Caching`_ for information on
A memcache speeds up server performance, and Nextcloud supports four
memcaches; refer to `Configuring Memory Caching`_ for information on
selecting and configuring a memcache.
* Storage
Local storage.
* Nextcloud Edition
Standard Edition. (See `Nextcloud Server or Enterprise Edition`_ for
comparisons of the Nextcloud editions.)
Mid-sized Enterprises
---------------------
* Number of users
150 to 1,000 users.
* Storage size
Up to 200TB.
* High availability level
Every component is fully redundant and can fail without service interruption.
Every component is fully redundant and can fail without service interruption.
Backups without service interruption
Recommended System Requirements
@ -148,6 +150,23 @@ Authentication via an existing LDAP or Active Directory server.
.. figure:: images/deprecs-2.png
:alt: Network diagram for mid-sized enterprise.
.. comment:
https://yuml.me
[load balancer]->[web server 1]
[load balancer]->[web server 2]
[web server 1]->[NFS]
[web server 2]->[NFS]
[web server 1]->[LDAP]
[web server 2]->[LDAP]
[web server 1]->[Redis]
[web server 2]->[Redis]
[web server 1]->[DB master]
[web server 2]->[DB master]
[web server 1]->[DB slave]
[web server 2]->[DB slave]
[DB master]->[DB slave]
* Components
* 2 to 4 application servers with 4 sockets and 32GB RAM.
* 2 DB servers with 4 sockets and 64GB RAM.
@ -155,42 +174,45 @@ Authentication via an existing LDAP or Active Directory server.
* NFS storage server as needed.
* Operating system
Enterprise grade Linux distribution with full support from OS vendor. Red
Hat Enterprise Linux or SUSE Linux Enterprise Server 12 are recommended.
Enterprise grade Linux distribution with full support from OS vendor. Red
Hat Enterprise Linux or Ubuntu 16.04 are recommended.
* SSL Configuration
The SSL termination is done in the HAProxy load balancer. A standard SSL
The SSL termination is done in the HAProxy load balancer. A standard SSL
certificate is needed, installed according to the `HAProxy documentation`_.
* Load Balancer
HAProxy running on a dedicated server in front of the application servers.
Sticky session needs to be used because of local session management on the
application servers.
HAProxy running on a dedicated server in front of the application servers.
Sticky session needs to be used because of local session management on the
application servers.
.. comment: (please add configuration details here)
.. comment: why sticky sessions? the nice thing about haproxy is that it can
send requests to the application server with the least load. redis or
memcached seem more appropriate. this is mid size already. the software
.. comment: (please add configuration details here)
.. comment: why sticky sessions? the nice thing about haproxy is that it can
send requests to the application server with the least load. redis or
memcached seem more appropriate. this is mid size already. the software
stack should be the same as for L`_
Frank: Yes. But this only works if haproxy can read the http stream which
means that we have to terminate SSL in the haproxy instead of the Web server.
Frank: Yes. But this only works if haproxy can read the http stream which
means that we have to terminate SSL in the haproxy instead of the Web server.
Totally possible. Whatever you prefer :-)
Jörn: AFAIK you need to do SSL offloading to do sticky sessions, because the
load balancer has to look into the http stream or rely on the client IP to
determine the Web server for the session. Not doing SSL offloading instead
requires you to use a shared session (via memcached or redis) because the
requests are distributed via round robin or least load. It allows you to
scale out the ssl load by adding more applicaton servers. So ... I think it
Jörn: AFAIK you need to do SSL offloading to do sticky sessions, because the
load balancer has to look into the http stream or rely on the client IP to
determine the Web server for the session. Not doing SSL offloading instead
requires you to use a shared session (via memcached or redis) because the
requests are distributed via round robin or least load. It allows you to
scale out the ssl load by adding more applicaton servers. So ... I think it
is exactly the other way round.
* Database
MySQL/MariaDB Galera cluster with master-master replication.
MySQL/MariaDB Galera cluster with master-slave replication. The slave is
only used as failover in case the master is down. This could be extended
with a load balancer infront to distribute writes to the master and reads
to the slave as well. (see "Database load balancer" below)
* Backup
Minimum daily backup without downtime. All MySQL/MariaDB statements should
Minimum daily backup without downtime. All MySQL/MariaDB statements should
be replicated to a backup MySQL/MariaDB slave instance.
* Create a snapshot on the NFS storage server.
* Create a snapshot on the NFS storage server.
* At the same time stop the MySQL replication.
* Create a MySQL dump of the backup slave.
* Push the NFS snapshot to the backup.
@ -199,55 +221,53 @@ Authentication via an existing LDAP or Active Directory server.
* Restart MySQL replication.
* Authentication
User authentication via one or several LDAP or Active Directory servers.
(See `User Authentication with LDAP`_ for information on configuring
User authentication via one or several LDAP or Active Directory servers.
(See `User Authentication with LDAP`_ for information on configuring
Nextcloud to use LDAP and AD.)
* LDAP
Read-only slaves should be deployed on every application server for
* LDAP
Read-only slaves should be deployed on every application server for
optimal scalability
* Session Management
Session management on the application server. PHP sessions are stored
in a tmpfs mounted at the operating system-specific session storage
location. You can find out where that is by running ``grep -R
'session.save_path' /etc/php5`` and then add it to the ``/etc/fstab`` file,
for example:
``echo "tmpfs /var/lib/php5/pool-www tmpfs defaults,noatime,mode=1777 0 0"
Session management on the application server. PHP sessions are stored
in a tmpfs mounted at the operating system-specific session storage
location. You can find out where that is by running ``grep -R
'session.save_path' /etc/php5`` and then add it to the ``/etc/fstab`` file,
for example:
``echo "tmpfs /var/lib/php5/pool-www tmpfs defaults,noatime,mode=1777 0 0"
>> /etc/fstab``.
* Memory Caching
A memcache speeds up server performance, and Nextcloud supports four
memcaches; refer to `Configuring Memory Caching`_ for information on
A memcache speeds up server performance, and Nextcloud supports four
memcaches; refer to `Configuring Memory Caching`_ for information on
selecting and configuring a memcache.
* Storage
Use an off-the-shelf NFS solution, such as IBM Elastic Storage or RedHat
Use an off-the-shelf NFS solution, such as IBM Elastic Storage or RedHat
Ceph.
* Nextcloud Edition
Enterprise Edition. (See `Nextcloud Server or Enterprise Edition`_ for
comparisons of the Nextcloud editions.)
Large Enterprises and Service Providers
---------------------------------------
* Number of users
5,000 to >100,000 users.
* Storage size
Up to 1 petabyte.
* High availabily level
Every component is fully redundant and can fail without service interruption.
Backups without service interruption
Backups without service interruption
Recommended System Requirements
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4 to 20 application/Web servers.
A cluster of two or more database servers.
A cluster of two or more database servers which are behind a load balancer to
send all writes to the master and reads to the slaves. (see "Database load balancer"
below)
Storage is an NFS server, or an object store that is S3 compatible.
@ -256,71 +276,112 @@ Cloud federation for a distributed setup over several data centers.
Authentication via an existing LDAP or Active Directory server, or SAML.
.. figure:: images/deprecs-3.png
:scale: 60%
:alt: Network diagram for large enterprise.
:alt: Network diagram for large enterprise.
.. comment:
https://yuml.me
[load balancer 1]->[web server 1|local LDAP slave]
[load balancer 1]->[web server 2|local LDAP slave]
[load balancer 1]->[web server 3|local LDAP slave]
[load balancer 1]->[web server 4|local LDAP slave]
[load balancer 2]->[web server 1]
[load balancer 2]->[web server 2]
[load balancer 2]->[web server 3]
[load balancer 2]->[web server 4]
[web server 1]->[NFS]
[web server 2]->[NFS]
[web server 3]->[NFS]
[web server 4]->[NFS]
[web server 1]->[LDAP]
[web server 2]->[LDAP]
[web server 3]->[LDAP]
[web server 4]->[LDAP]
[web server 1]->[Redis 1]
[web server 2]->[Redis 1]
[web server 3]->[Redis 1]
[web server 4]->[Redis 1]
[web server 1]->[Redis 2]
[web server 2]->[Redis 2]
[web server 3]->[Redis 2]
[web server 4]->[Redis 2]
[Redis 1]->[Redis 2]
[Redis 2]->[Redis 1]
[web server 1]->[DB load balancer]
[web server 2]->[DB load balancer]
[web server 3]->[DB load balancer]
[web server 4]->[DB load balancer]
[DB load balancer]->[DB master]
[DB load balancer]->[DB slave 1]
[DB load balancer]->[DB slave 2]
[DB load balancer]->[DB slave 3]
[DB master]->[DB slave 1]
[DB master]->[DB slave 2]
[DB master]->[DB slave 3]
* Components
* 4 to 20 application servers with 4 sockets and 64GB RAM.
* 4 DB servers with 4 sockets and 128GB RAM
* 2 Hardware load balancer, for example BIG IP from F5
* 4 DB servers with 4 sockets and 128GB RAM plus a DB load balancer
(see "Database load balancer" below)
* 2 load balancer - either HAProxy with keepalived (heartbeat) and a shared
virutal IP address as a software solution or a hardware load balancer. For
the HAProxy we recommend at least 2 sockets and 16GB RAM each.
* NFS storage server as needed.
* Operating system
RHEL 7 with latest service packs.
Enterprise grade Linux distribution with full support from OS vendor. Red
Hat Enterprise Linux or Ubuntu 16.04 are recommended.
* SSL Configuration
The SSL termination is done in the load balancer. A standard SSL certificate
is needed, installed according to the load balancer documentation.
The SSL termination is done in the load balancer. A standard SSL certificate
is needed, installed according to the load balancer documentation.
* Load Balancer
A redundant hardware load-balancer with heartbeat, for example `F5 Big-IP`_.
A redundant load-balancer with heartbeat, for example `HAProxy`_.
This runs two load balancers in front of the application servers.
* Database
MySQL/MariaDB Galera Cluster with 4x master -- master replication.
MySQL/MariaDB Galera Cluster with master - slave replication (master & 3 slaves).
The load balancer infront distributes writes to the master and reads to the
slaves. (see "Database load balancer" below)
* Backup
Minimum daily backup without downtime. All MySQL/MariaDB statements should
Minimum daily backup without downtime. All MySQL/MariaDB statements should
be replicated to a backup MySQL/MariaDB slave instance.
* Create a snapshot on the NFS storage server.
* Create a snapshot on the NFS storage server.
* At the same time stop the MySQL replication.
* Create a MySQL dump of the backup slave.
* Push the NFS snapshot to the backup.
* Push the MySQL dump to the backup.
* Delete the NFS snapshot.
* Restart MySQL replication.
* Authentication
User authentication via one or several LDAP or Active Directory
User authentication via one or several LDAP or Active Directory
servers, or SAML/Shibboleth. (See `User Authentication with LDAP`_.)
* LDAP
Read-only slaves should be deployed on every application server for
Read-only slaves should be deployed on every application server for
optimal scalability.
* Session Management
Redis should be used for the session management storage.
* Caching
Redis for distributed in-memory caching (see `Configuring Memory
Redis for distributed in-memory caching (see `Configuring Memory
Caching`_).
* Storage
An off-the-shelf NFS solution should be used. Examples are IBM Elastic
Storage or RedHAT Ceph. Optionally, an S3 compatible object store can also
An off-the-shelf NFS solution should be used. Examples are IBM Elastic
Storage or RedHAT Ceph. Optionally, an S3 compatible object store can also
be used.
* Nextcloud Edition
Enterprise Edition. (See `Nextcloud Server or Enterprise Edition`_ for
comparisons of the Nextcloud editions.)
Hardware Considerations
-----------------------
* Solid-state drives (SSDs) for I/O.
* Separate hard disks for storage and database, SSDs for databases.
* Multiple network interfaces to distribute server synchronisation and backend
* Multiple network interfaces to distribute server synchronisation and backend
traffic across multiple subnets.
Single Machine / Scale-Up Deployment
@ -330,17 +391,17 @@ The single-machine deployment is widely used in the community.
Pros:
* Easy setup: no session storage daemon, use tmpfs and memory caching to
* Easy setup: no session storage daemon, use tmpfs and memory caching to
enhance performance, local storage.
* No network latency to consider.
* To scale buy a bigger CPU, more memory, larger hard drive, or additional hard
* To scale buy a bigger CPU, more memory, larger hard drive, or additional hard
drives.
Cons:
* Fewer high availability options.
* The amount of data in Nextcloud tends to continually grow. Eventually a
single machine will not scale; I/O performance decreases and becomes a
* The amount of data in Nextcloud tends to continually grow. Eventually a
single machine will not scale; I/O performance decreases and becomes a
bottleneck with multiple up- and downloads, even with solid-state drives.
Scale-Out Deployment
@ -348,13 +409,15 @@ Scale-Out Deployment
Provider setup:
* DNS round robin to HAProxy servers (2-n, SSL offloading, cache static
* DNS round robin to HAProxy servers (2-n, SSL offloading, cache static
resources)
* Least load to Apache servers (2-n)
* Memcached/Redis for shared session storage (2-n)
* Database cluster with single Master, multiple slaves and proxy to split
requests accordingly (2-n)
* GPFS or Ceph via phprados (2-n, 3 to be safe, Ceph 10+ nodes to see speed
* Database cluster with single Master, multiple slaves and proxy to split
requests accordingly (2-n) - HAProxy or `MaxScale`_ are possible proxy
solutions to load balance the writes to the master and reads to the slaves
(see "Database load balancer" below)
* GPFS or Ceph via phprados (2-n, 3 to be safe, Ceph 10+ nodes to see speed
benefits under load)
Pros:
@ -367,7 +430,7 @@ Cons:
* More complicated to setup.
* Network becomes the bottleneck (10GB Ethernet recommended).
* Currently DB filecache table will grow rapidly, making migrations painful in
* Currently DB filecache table will grow rapidly, making migrations painful in
case the table is altered.
What About Nginx / PHP-FPM?
@ -379,10 +442,21 @@ But on uploads stores the whole file on disk before handing it over to PHP-FPM.
A Single Master DB is Single Point of Failure, Does Not Scale
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When master fails another slave can become master. However, the increased
complexity carries some risks: Multi-master has the risk of split brain, and
deadlocks. Nextcloud tries to solve the problem of deadlocks with high-level
file locking.
When master fails another slave can become master.
A multi-master setup with Galera cluster is not supported, because we require
``READ-COMMITTED`` as transaction isolation level. `Galera doesn't support this
with a master-master replication`_ which will lead to deadlocks during uploads
of multiple files into one directory for example.
Database load balancer
^^^^^^^^^^^^^^^^^^^^^^
When Galera cluster is used as DB cluster solution, we recommend to use
`MaxScale`_ as load balancer infront of the cluster to distribute writes to
the master node and reads to the slaves.
As alternative also `HAProxy can be used as load balancer for the DB`_.
Software Considerations
-----------------------
@ -390,81 +464,78 @@ Software Considerations
Operating System
^^^^^^^^^^^^^^^^
We are dependent on distributions that offer an easy way to install the various
components in up-to-date versions. Nextcloud has a partnership with RedHat
and SUSE for customers who need commercial support. Canonical, the parent
company of Ubuntu Linux, also offers enterprise service and support. Debian
and Ubuntu are free of cost, and include newer software packages. CentOS is the
community-supported free-of-cost Red Hat Enterprise Linux clone. openSUSE is
community-supported, and includes many of the same system administration tools
as SUSE Linux Enterprise Server.
We are dependent on distributions that offer an easy way to install the various
components in up-to-date versions. We recommend Red Hat Enterprise Linux 7 or
Ubuntu 16.04 - for both commercial support can be purchased. Debian
and Ubuntu are free of cost, and include newer software packages. CentOS is the
community-supported free-of-cost Red Hat Enterprise Linux clone.
Web server
^^^^^^^^^^
Taking Apache and Nginx as the contenders, Apache with mod_php is currently the
best option, as Nginx does not support all features necessary for enterprise
deployments. Mod_php is recommended instead of PHP_FPM, because in scale-out
Taking Apache and Nginx as the contenders, Apache with mod_php is currently the
best option, as Nginx does not support all features necessary for enterprise
deployments. Mod_php is recommended instead of PHP_FPM, because in scale-out
deployments separate PHP pools are simply not necessary.
Relational Database
^^^^^^^^^^^^^^^^^^^
More often than not the customer already has an opinion on what database to
use. In general, the recommendation is to use what their database administrator
is most familiar with. Taking into account what we are seeing at customer
deployments, we recommend MySQL/MariaDB in a master-slave deployment with a
MySQL proxy in front of them to send updates to master, and selects to the
slave(s).
More often than not the customer already has an opinion on what database to
use. In general, the recommendation is to use what their database administrator
is most familiar with. Taking into account what we are seeing at customer
deployments, we recommend MySQL/MariaDB in a master - slave deployment with a
MySQL proxy in front of them to send updates to master, and selects to the
slave(s). (see "Database load balancer" above)
.. comment: MySQL locks tables for schema updates and might even have to copy
the whole table. That is pretty much a non-starter for migrations unless you
are using a scale out deployment where you can apply the schema changes to
each slave individually. Even then each migration might take several hours.
.. comment: MySQL locks tables for schema updates and might even have to copy
the whole table. That is pretty much a non-starter for migrations unless you
are using a scale out deployment where you can apply the schema changes to
each slave individually. Even then each migration might take several hours.
Make sure you have enough disk space. You have been warned.
.. comment: Currently, Nextcloud uses the utf8 character set with utf8_bin
collation on MySQL installations. As a result 4 byte UTF characters like
emojis cannot be used. This can be fixed by [moving to
utf8mb4/utf8mb4_bin](https://github.com/owncloud/core/issues/7030).
.. comment: By default Nextcloud uses the utf8 character set with utf8_bin
collation on MySQL installations. As a result 4 byte UTF characters like
emojis cannot be used. See the config.php option ``'mysql.utf8mb4'`` to
switch to 4 byte UTF characters on MySQL.
The second best option is PostgreSQL (alter table does not lock table, which
makes migration less painful) although we have yet to find a customer who uses a
The second best option is PostgreSQL (alter table does not lock table, which
makes migration less painful) although we have yet to find a customer who uses a
master-slave setup.
.. comment: PostgreSQL may produce excessive amounts of dead tuples due to
.. comment: PostgreSQL may produce excessive amounts of dead tuples due to
Nextcloud transactions preventing the execution of the autovacum process.
What about the other DBMS?
* Sqlite is adequate for simple testing, and for low-load single-user
* Sqlite is adequate for simple testing, and for low-load single-user
deployments. It is not adequate for production systems.
* Microsoft SQL Server is not a supported option.
* Oracle DB is the de facto standard at large enterprises and is fully
supported with Nextcloud Enterprise Edition only.
* For Oracle DB support please `contact the Nextcloud team`_ to get more
information on this.
File Storage
------------
While many customers are starting with NFS, sooner or later that requires scale-out storage. Currently the options are GPFS or GlusterFS, or an object store protocol like S3 (supported in Enterprise Edition only) or Swift. S3 also allows access to Ceph Storage.
While many customers are starting with NFS, sooner or later that requires scale-out storage. Currently the options are GPFS or GlusterFS, or an object store protocol like S3 or Swift. S3 also allows access to Ceph Storage.
.. comment: A proof of concept implementation based on
[phprados](https://github.com/ceph/phprados) that talks directly to a
[ceph](http://ceph.com/) cluster without having to use temp files is [in
.. comment: A proof of concept implementation based on
[phprados](https://github.com/ceph/phprados) that talks directly to a
[ceph](http://ceph.com/) cluster without having to use temp files is [in
development](https://github.com/owncloud/objectstore/pull/26).
.. comment: NFS can be used but needs to be micro-managed to distribute users
on multiple storages. If you want to go that route configure ldap to provide
a custom home folder location. That allows you to move each users data
.. comment: NFS can be used but needs to be micro-managed to distribute users
on multiple storages. If you want to go that route configure ldap to provide
a custom home folder location. That allows you to move each users data
folder to different nfs mounts.
Session Storage
---------------
* Redis: provides persistence, nice graphical inspection tools available,
* Redis: provides persistence, nice graphical inspection tools available,
supports Nextcloud high-level file locking.
* If Shibboleth is a requirement you must use Memcached, and it can also be
* If Shibboleth is a requirement you must use Memcached, and it can also be
used to scale-out shibd session storage (see `Memcache StorageService`_).
.. comment: High Availability / Failover deployment
@ -474,34 +545,43 @@ References
----------
`Database High Availability`_
`Performance enhancements for Apache and PHP`_
`How to Set Up a Redis Server as a Session Handler for PHP on Ubuntu 14.04`_
.. TODO ON RELEASE: Update version number below on release
.. _Maintenance:
.. _Maintenance:
https://docs.nextcloud.org/server/11/admin_manual/maintenance/index.html
.. _User Authentication with LDAP:
https://docs.nextcloud.org/server/11/admin_manual/configuration_user/user_auth_ldap.html
.. _Configuring Memory Caching:
.. _Configuring Memory Caching:
https://docs.nextcloud.org/server/11/admin_manual/configuration_server/caching_configuration.html
.. _Nextcloud Server or Enterprise Edition:
.. _Nextcloud Server or Enterprise Edition:
https://nextcloud.com/enterprise/
.. _F5 Big-IP: https://f5.com/products/big-ip/
.. _Memcache StorageService:
.. _Memcache StorageService:
https://wiki.shibboleth.net/confluence/display/SHIB2/
NativeSPStorageService#NativeSPStorageService-MemcacheStorageService
.. _Database High Availability:
.. _Database High Availability:
http://www.severalnines.com/blog/become-mysql-dba-blog-series-database-high-
availability
.. _Performance enhancements for Apache and PHP:
http://blog.bitnami.com/2014/06/performance-enhacements-for-apache-and.html
.. _How to Set Up a Redis Server as a Session Handler for PHP on Ubuntu 14.04:
.. _Performance enhancements for Apache and PHP:
http://blog.bitnami.com/2014/06/performance-enhacements-for-apache-and.html
.. _How to Set Up a Redis Server as a Session Handler for PHP on Ubuntu 14.04:
https://www.digitalocean.com/community/tutorials/how-to-set-up-a-redis-server
-as -a-session-handler-for-php-on-ubuntu-14-04
.. _HAProxy documentation:
http://www.haproxy.org/#docs
.. _Galera doesn't support this with a master-master replication:
http://galeracluster.com/documentation-webpages/isolationlevels.html#understanding-isolation-levels
.. _contact the Nextcloud team:
https://nextcloud.com/contact/
.. _HAProxy can be used as load balancer for the DB:
https://severalnines.com/blog/avoiding-deadlocks-galera-set-haproxy-single-node-writes-and-multi-node-reads
.. _MaxScale:
https://mariadb.com/products/mariadb-maxscale
.. _HAProxy:
http://www.haproxy.org/

BIN
admin_manual/installation/images/deprecs-1.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 14 KiB

After

Width:  |  Height:  |  Size: 2.9 KiB

BIN
admin_manual/installation/images/deprecs-2.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 43 KiB

After

Width:  |  Height:  |  Size: 20 KiB

BIN
admin_manual/installation/images/deprecs-3.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 164 KiB

After

Width:  |  Height:  |  Size: 54 KiB

16
admin_manual/installation/installation_wizard.rst
View File

@ -146,25 +146,24 @@ replace the ``htuser`` and ``htgroup`` variables with your HTTP user and group::
#!/bin/bash
ocpath='/var/www/nextcloud'
datapath='/var/www/nextcloud/data'
htuser='www-data'
htgroup='www-data'
rootuser='root'
printf "Creating possible missing Directories\n"
mkdir -p $ocpath/data
mkdir -p $ocpath/assets
mkdir -p $ocpath/updater
printf "chmod Files and Directories\n"
find ${ocpath} -type f -print0 | xargs -0 chmod 0640
find ${ocpath} -type d -print0 | xargs -0 chmod 0750
find ${ocpath}/ -type f -print0 | xargs -0 chmod 0640
find ${ocpath}/ -type d -print0 | xargs -0 chmod 0750
printf "chown Directories\n"
chown -R ${rootuser}:${htgroup} ${ocpath}/
chown -R ${htuser}:${htgroup} ${ocpath}/apps/
chown -R ${htuser}:${htgroup} ${ocpath}/assets/
chown -R ${htuser}:${htgroup} ${ocpath}/config/
chown -R ${htuser}:${htgroup} ${ocpath}/data/
chown -R ${htuser}:${htgroup} ${datapath}
chown -R ${htuser}:${htgroup} ${ocpath}/themes/
chown -R ${htuser}:${htgroup} ${ocpath}/updater/
@ -176,10 +175,10 @@ replace the ``htuser`` and ``htgroup`` variables with your HTTP user and group::
chmod 0644 ${ocpath}/.htaccess
chown ${rootuser}:${htgroup} ${ocpath}/.htaccess
fi
if [ -f ${ocpath}/data/.htaccess ]
if [ -f ${datapath}/.htaccess ]
then
chmod 0644 ${ocpath}/data/.htaccess
chown ${rootuser}:${htgroup} ${ocpath}/data/.htaccess
chmod 0644 ${datapath}/.htaccess
chown ${rootuser}:${htgroup} ${datapath}/.htaccess
fi
If you have customized your Nextcloud installation and your filepaths are
@ -196,7 +195,6 @@ and files:
* The :file:`apps/` directory should be owned by ``[HTTP user]:[HTTP group]``
* The :file:`config/` directory should be owned by ``[HTTP user]:[HTTP group]``
* The :file:`themes/` directory should be owned by ``[HTTP user]:[HTTP group]``
* The :file:`assets/` directory should be owned by ``[HTTP user]:[HTTP group]``
* The :file:`data/` directory should be owned by ``[HTTP user]:[HTTP group]``
* The :file:`[ocpath]/.htaccess` file should be owned by ``root:[HTTP group]``
* The :file:`data/.htaccess` file should be owned by ``root:[HTTP group]``

69
admin_manual/installation/nginx_examples.rst
View File

@ -3,8 +3,7 @@ Nginx Example Configurations
============================
This page covers example Nginx configurations to use with running an Nextcloud
server. Note that Nginx is not officially supported, and this page is
community-maintained. (Thank you, contributors!)
server. This page is community-maintained. (Thank you, contributors!)
- You need to insert the following code into **your Nginx configuration file.**
@ -43,7 +42,9 @@ Suppressing Log Messages
If you're seeing meaningless messages in your logfile, for example `client
denied by server configuration: /var/www/data/htaccesstest.txt
<https://forum.owncloud.org/viewtopic.php?f=17&t=20217>`_, add this section to
your nginx configuration to suppress them::
your nginx configuration to suppress them:
.. code-block:: nginx
location = /data/htaccesstest.txt {
allow all;
@ -58,11 +59,15 @@ A common issue with custom nginx configs is that JavaScript (.js)
or CSS (.css) files are not served properly leading to a 404 (File not found)
error on those files and a broken webinterface.
This could be caused by the::
This could be caused by the:
.. code-block:: nginx
location ~* \.(?:css|js)$ {
block shown above not located **below** the::
block shown above not located **below** the:
.. code-block:: nginx
location ~ \.php(?:$|/) {
@ -72,23 +77,21 @@ or CSS (.css) files via gzip could also cause such issues.
Performance Tuning
==================
`nginx (<1.9.5) <ngx_http_spdy_module
<http://nginx.org/en/docs/http/ngx_http_spdy_module.html>`_
`nginx (+1.9.5) <ngx_http_http2_module
<http://nginx.org/en/docs/http/ngx_http_v2_module.html>`_
* `nginx (<1.9.5) <ngx_http_spdy_module <http://nginx.org/en/docs/http/ngx_http_spdy_module.html>`_
* `nginx (+1.9.5) <ngx_http_http2_module <http://nginx.org/en/docs/http/ngx_http_v2_module.html>`_
To use http_v2 for nginx you have to check two things:
1.) be aware that this module is not built in by default due to a dependency
to the openssl version used on your system. It will be enabled with the
``--with-http_v2_module`` configuration parameter during compilation. The
dependency should be checked automatically. You can check the presence of
http_v2 with ``nginx -V 2>&1 | grep http_v2 -o``. An example of how to
compile nginx can be found in section "Configure nginx with the
``nginx-cache-purge`` module" below.
1.) be aware that this module is not built in by default due to a dependency
to the openssl version used on your system. It will be enabled with the
``--with-http_v2_module`` configuration parameter during compilation. The
dependency should be checked automatically. You can check the presence of
http_v2 with ``nginx -V 2>&1 | grep http_v2 -o``. An example of how to
compile nginx can be found in section "Configure nginx with the
``nginx-cache-purge`` module" below.
2.) When you have used SPDY before, the nginx config has to be changed from
``listen 443 ssl spdy;`` to ``listen 443 ssl http2;``
2.) When you have used SPDY before, the nginx config has to be changed from
``listen 443 ssl spdy;`` to ``listen 443 ssl http2;``
nginx: caching Nextcloud gallery thumbnails
===========================================
@ -247,7 +250,9 @@ Configure nginx with the ``nginx-cache-purge`` module
sudo vi /etc/nginx/sites-enabled/{your-nextcloud-nginx-config-file}
Add at the *beginning*, but *outside* the ``server{}`` block::
Add at the *beginning*, but *outside* the ``server{}`` block:
.. code-block:: nginx
# cache_purge
fastcgi_cache_path {path} levels=1:2 keys_zone=NEXTCLOUD:100m inactive=60m;
@ -261,15 +266,18 @@ Add at the *beginning*, but *outside* the ``server{}`` block::
.. note:: Please adopt or delete any regex line in the ``map`` block according
your needs and the Nextcloud version used.
As an alternative to mapping, you can use as many ``if`` statements in
your server block as necessary::
your server block as necessary:
.. code-block:: nginx
set $skip_cache 1;
if ($request_uri ~* "thumbnail.php") { set $skip_cache 0; }
if ($request_uri ~* "/apps/galleryplus/") { set $skip_cache 0; }
if ($request_uri ~* "/apps/gallery/") { set $skip_cache 0; }
Add *inside* the ``server{}`` block, as an example of a configuration::
Add *inside* the ``server{}`` block, as an example of a configuration:
.. code-block:: nginx
# cache_purge (with $http_cookies we have unique keys for the user)
fastcgi_cache_key $http_cookie$request_method$host$request_uri;
@ -277,13 +285,14 @@ Add *inside* the ``server{}`` block, as an example of a configuration::
fastcgi_ignore_headers Cache-Control Expires Set-Cookie;
location ~ \.php(?:$/) {
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_split_path_info ^(.+\.php)(/.*)$;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param HTTPS on;
fastcgi_pass php-handler;
fastcgi_request_buffering off; #Available since nginx 1.7.11
# cache_purge
fastcgi_cache_bypass $skip_cache;
@ -296,13 +305,15 @@ Add *inside* the ``server{}`` block, as an example of a configuration::
.. note:: Note regarding the ``fastcgi_pass`` parameter:
Use whatever fits your configuration. In the example above, an ``upstream``
was defined in an nginx global configuration file.
This may look like::
This may look like:
.. code-block:: nginx
upstream php-handler {
server unix:/var/run/php5-fpm.sock;
# or
# server 127.0.0.1:9000;
}
upstream php-handler {
server unix:/var/run/php5-fpm.sock;
# or
# server 127.0.0.1:9000;
}
3. **Test the configuration**

22
admin_manual/installation/nginx_nextcloud_9x.rst
View File

@ -1,6 +1,6 @@
==================================================
Nginx Configuration for the Nextcloud 9.x Branches
==================================================
===================
Nginx Configuration
===================
The following configuration should be used when Nextcloud is placed in the
webroot of your Nginx installation. Be careful about line breaks if you copy
@ -18,7 +18,7 @@ Nextcloud in the webroot of nginx
The following config should be used when Nextcloud is placed in the webroot of
your nginx installation.
::
.. code-block:: nginx
upstream php-handler {
server 127.0.0.1:9000;
@ -84,9 +84,6 @@ your nginx installation.
# This module is currently not supported.
#pagespeed off;
error_page 403 /core/templates/403.php;
error_page 404 /core/templates/404.php;
location / {
rewrite ^ /index.php$uri;
}
@ -99,8 +96,8 @@ your nginx installation.
}
location ~ ^/(?:index|remote|public|cron|core/ajax/update|status|ocs/v[12]|updater/.+|ocs-provider/.+|core/templates/40[34])\.php(?:$|/) {
fastcgi_split_path_info ^(.+\.php)(/.*)$;
include fastcgi_params;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param HTTPS on;
@ -151,7 +148,7 @@ Nextcloud in a subdir of nginx
The following config should be used when Nextcloud is placed within a subdir of
your nginx installation.
::
.. code-block:: nginx
upstream php-handler {
server 127.0.0.1:9000;
@ -221,10 +218,7 @@ your nginx installation.
# Uncomment if your server is build with the ngx_pagespeed module
# This module is currently not supported.
#pagespeed off;
error_page 403 /nextcloud/core/templates/403.php;
error_page 404 /nextcloud/core/templates/404.php;
location /nextcloud {
rewrite ^ /nextcloud/index.php$uri;
}
@ -237,8 +231,8 @@ your nginx installation.
}
location ~ ^/nextcloud/(?:index|remote|public|cron|core/ajax/update|status|ocs/v[12]|updater/.+|ocs-provider/.+|core/templates/40[34])\.php(?:$|/) {
fastcgi_split_path_info ^(.+\.php)(/.*)$;
include fastcgi_params;
fastcgi_split_path_info ^(.+\.php)(/.+)$;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param HTTPS on;

26
admin_manual/installation/selinux_configuration.rst
View File

@ -12,22 +12,22 @@ The following settings should work for most SELinux systems that use the
default distro profiles. Run these commands as root, and remember to adjust the filepaths
in these examples for your installation::
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/nextcloud/data'
restorecon '/var/www/html/nextcloud/data'
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/nextcloud/config'
restorecon '/var/www/html/nextcloud/config'
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/nextcloud/apps'
restorecon '/var/www/html/nextcloud/apps'
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/nextcloud/data(/.*)?'
restorecon -v -R '/var/www/html/nextcloud/data'
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/nextcloud/config(/.*)?'
restorecon -v -R '/var/www/html/nextcloud/config'
semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/nextcloud/apps(/.*)?'
restorecon -v -R '/var/www/html/nextcloud/apps'
If you uninstall Nextcloud you need to remove the Nextcloud directory labels. To do
this execute the following commands as root after uninstalling Nextcloud::
semanage fcontext -d -t httpd_sys_rw_content_t '/var/www/html/nextcloud/data'
restorecon '/var/www/html/nextcloud/data'
semanage fcontext -d -t httpd_sys_rw_content_t '/var/www/html/nextcloud/config'
restorecon '/var/www/html/nextcloud/config'
semanage fcontext -d -t httpd_sys_rw_content_t '/var/www/html/nextcloud/apps'
restorecon '/var/www/html/nextcloud/apps'
semanage fcontext -d -t httpd_sys_rw_content_t '/var/www/html/nextcloud/data(/.*)?'
restorecon -v -R '/var/www/html/nextcloud/data'
semanage fcontext -d -t httpd_sys_rw_content_t '/var/www/html/nextcloud/config(/.*)?'
restorecon -v -R '/var/www/html/nextcloud/config'
semanage fcontext -d -t httpd_sys_rw_content_t '/var/www/html/nextcloud/apps(/.*)?'
restorecon -v -R '/var/www/html/nextcloud/apps'
If you have customized SELinux policies and these examples do not work, you must give the
HTTP server write access to these directories::
@ -80,4 +80,4 @@ For general Troubleshooting of SELinux and its profiles try to install the packa
sealert -a /var/log/audit/audit.log > /path/to/mylogfile.txt
to get a report which helps you configuring your SELinux profiles.
to get a report which helps you configuring your SELinux profiles.

38
admin_manual/installation/source_installation.rst
View File

@ -35,30 +35,31 @@ The Nextcloud .tar archive contains all of the required PHP modules. This
section lists all required and optional PHP modules. Consult the `PHP manual
<http://php.net/manual/en/extensions.php>`_ for more information on modules.
Your Linux distribution should have packages for all required modules. You can
check the precense of a module by typing ``php -m | grep -i <module_name>``.
check the presence of a module by typing ``php -m | grep -i <module_name>``.
If you get a result, the module is present.
Required:
* php5 (>= 5.4)
* PHP (>= 5.6, 7.0 or 7.1)
* PHP module ctype
* PHP module dom
* PHP module GD
* PHP module iconv
* PHP module JSON
* PHP module libxml (Linux package libxml2 must be >=2.7.0)
* PHP module mb multibyte
* PHP module mbstring
* PHP module posix
* PHP module SimpleXML
* PHP module XMLReader
* PHP module XMLWriter
* PHP module zip
* PHP module zlib
Database connectors (pick the one for your database:)
* PHP module sqlite (>= 3, usually not recommended for performance reasons)
* PHP module pdo_sqlite (>= 3, usually not recommended for performance reasons)
* PHP module pdo_mysql (MySQL/MariaDB)
* PHP module pgsql (requires PostgreSQL >= 9.0)
* PHP module pdo_pgsql (requires PostgreSQL >= 9.0)
*Recommended* packages:
@ -87,10 +88,9 @@ Recommended for specific apps (*optional*):
For enhanced server performance (*optional*) select one of the following
memcaches:
* PHP module apc
* PHP module apcu
* PHP module apcu (>= 4.0.6)
* PHP module memcached
* PHP module redis (>= 2.2.5, required for Transactional File Locking)
* PHP module redis (>= 2.2.6, required for Transactional File Locking)
See :doc:`../configuration_server/caching_configuration` to learn how to select
and configure a memcache.
@ -113,23 +113,23 @@ If ``mod_webdav`` is enabled you must disable it for Nextcloud. (See
.. _ubuntu_installation_label:
Example Installation on Ubuntu 14.04 LTS Server
Example Installation on Ubuntu 16.04 LTS Server
-----------------------------------------------
On a machine running a pristine Ubuntu 14.04 LTS server, install the
On a machine running a pristine Ubuntu 16.04 LTS server, install the
required and recommended modules for a typical Nextcloud installation, using
Apache and MariaDB, by issuing the following commands in a terminal::
apt-get install apache2 mariadb-server libapache2-mod-php5
apt-get install php5-gd php5-json php5-mysql php5-curl
apt-get install php5-intl php5-mcrypt php5-imagick
apt-get install apache2 mariadb-server libapache2-mod-php7.0
apt-get install php7.0-gd php7.0-json php7.0-mysql php7.0-curl php7.0-mbstring
apt-get install php7.0-intl php7.0-mcrypt php-imagick php7.0-xml php7.0-zip
* This installs the packages for the Nextcloud core system.
``libapache2-mod-php5`` provides the following PHP extensions: ``bcmath bz2
``libapache2-mod-php7.0`` provides the following PHP extensions: ``bcmath bz2
calendar Core ctype date dba dom ereg exif fileinfo filter ftp gettext hash
iconv libxml mbstring mhash openssl pcre Phar posix Reflection session shmop
iconv libxml mhash openssl pcre Phar posix Reflection session shmop
SimpleXML soap sockets SPL standard sysvmsg sysvsem sysvshm tokenizer wddx
xml xmlreader xmlwriter zip zlib``. If you are planning
xmlreader xmlwriter zlib``. If you are planning
on running additional apps, keep in mind that they might require additional
packages. See :ref:`prerequisites_label` for details.
@ -249,7 +249,7 @@ Additional Apache Configurations
authentication on a parent folder (via e.g. an ``AuthType Basic``
directive), you can turn off the authentication specifically for the
Nextcloud entry. Following the above example configuration file, add the
following line in the ``<Directory`` section::
following line in the ``<Directory>`` section::
Satisfy Any
@ -363,11 +363,11 @@ ini file. This can be the case, for example, for the ``date.timezone`` setting.
php-fpm Configuration Notes
---------------------------
**Security: Use at least PHP => 5.5.22 or >= 5.6.6**
**Security: Use at least PHP >= 5.6.6**
Due to `a bug with security implications <https://bugs.php.net/bug.php?id=64938>`_
in older PHP releases with the handling of XML data you are highly encouraged to run
at least PHP 5.5.22 or 5.6.6 when in a threaded environment.
at least PHP 5.6.6 when in a threaded environment.
**System environment variables**

29
admin_manual/installation/system_requirements.rst
View File

@ -14,28 +14,26 @@ Recommended Setup for Running Nextcloud
For best performance, stability, support, and full functionality we recommend:
* Red Hat Enterprise Linux 7
* Red Hat Enterprise Linux 7 / Ubuntu 16.04 LTS
* MySQL/MariaDB
* PHP 5.4 +
* PHP 7.0 +
* Apache 2.4 with mod_php
Supported Platforms
-------------------
* Server: Linux (Debian 7, SUSE Linux Enterprise Server 11 SP3 & 12,
Red Hat Enterprise Linux/Centos 6.5 and 7 (7 is 64-bit only), Ubuntu 12.04
LTS, 14.04 LTS, 14.10)
* Web server: Apache 2 with mod_php
Red Hat Enterprise Linux/CentOS 6.5 and 7 (7 is 64-bit only), Ubuntu 14.04 LTS, 16.04 LTS)
* Web server: Apache 2 (mod_php, php-fpm) or Nginx (php-fpm)
* Databases: MySQL/MariaDB 5.5+; PostgreSQL; Oracle 11g (currently only possible
if you `contact us <https://nextcloud.com/enterprise>` as part of a subscription)
* PHP 5.4 + required
* PHP 5.6 + required
* Hypervisors: Hyper-V, VMware ESX, Xen, KVM
* Desktop: Windows XP SP3 (EoL Q2 2015), Windows 7+, Mac OS X 10.7+ (64-bit
only), Linux (CentOS 6.5, 7 (7 is 64-bit only), Ubuntu 12.04 LTS, 14.04 LTS,
14.10, Fedora 20, 21, openSUSE 12.3, 13, Debian 7 & 8).
* Mobile apps: iOS 7+, Android 4+
* Web browser: IE9+ (except Compatibility Mode), Firefox 14+, Chrome 18+,
Safari 5+
* Web browser: IE11+, Microsoft Edge, Firefox 14+, Chrome 18+, Safari 7+
See :doc:`source_installation` for minimum software versions for installing
Nextcloud.
@ -48,3 +46,18 @@ The following is currently required if you're running Nextcloud together with a
* Disabled or BINLOG_FORMAT = MIXED configured Binary Logging (See: :ref:`db-binlog-label`)
* InnoDB storage engine (MyISAM is not supported)
* "READ COMMITED" transaction isolation level (See: :ref:`db-transaction-label`)
Emoji (UTF8 4-byte) support with MySQL / MariaDB
================================================
If you want to use UTF8 4-byte characters such as Emojis on your server, the database needs to be created with character set ``utf8mb4`` and collate ``utf8mb4_general_ci``, e.g.::
CREATE DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
Additionally the following InnoDB settings need to be set::
[mysqld]
innodb_large_prefix=on
innodb_file_format=barracuda
innodb_file_per_table=true
See :doc:`../maintenance/mysql_4byte_support` for more information.

5
admin_manual/issues/general_troubleshooting.rst
View File

@ -6,8 +6,7 @@ If you have trouble installing, configuring or maintaining Nextcloud, please
refer to our community support channels:
* `The Nextcloud Forums`_
.. note:: The Nextcloud forums have a `FAQ page`_ where each topic corresponds
The Nextcloud forums have a `FAQ page`_ where each topic corresponds
to typical mistakes or frequently occurring issues
* `The Nextcloud forums`_
@ -35,6 +34,8 @@ configuration report with the :ref:`occ config command
<config_commands_label>`, with passwords automatically obscured.
.. _the Nextcloud Forums: https://help.nextcloud.com
.. _FAQ page: https://help.nextcloud.com/c/faq
.. _bugtracker: https://github.com/nextcloud/server/issues
.. _webchat: http://webchat.freenode.net/?channels=nextcloud
https://docs.nextcloud.org/server/11/developer_manual/bugtracker/index.html
.. TODO ON RELEASE: Update version number above on release

4
admin_manual/maintenance/backup.rst
View File

@ -20,13 +20,15 @@ your Nextcloud environment. You could use this command::
Backup Database
---------------
.. warning:: Before restoring a backup see :doc:`restore`
MySQL/MariaDB
^^^^^^^^^^^^^
MySQL or MariaDB, which is a drop-in MySQL replacement, is the recommended
database engine. To backup MySQL/MariaDB::
mysqldump --lock-tables -h [server] -u [username] -p[password] [db_name] > nextcloud-sqlbkp_`date +"%Y%m%d"`.bak
mysqldump --single-transaction -h [server] -u [username] -p[password] [db_name] > nextcloud-sqlbkp_`date +"%Y%m%d"`.bak
SQLite
^^^^^^

1
admin_manual/maintenance/index.rst
View File

@ -13,3 +13,4 @@ Maintenance
manual_upgrade
restore
migrating
mysql_4byte_support

25
admin_manual/maintenance/manual_upgrade.rst
View File

@ -16,13 +16,13 @@ The other way is by entering your ``config.php`` file and changing
``'maintenance' => false,`` to ``'maintenance' => true,``.
1. Back up your existing Nextcloud Server database, data directory, and
``config.php`` file. (See :doc:`backup`.)
``config.php`` file. (See :doc:`backup`, for restore information see :doc:`restore`)
2. Download and unpack the latest Nextcloud Server release (Archive file) from
`nextcloud.com/install/`_ into an empty directory outside
of your current installation.
.. note:: To unpack your new tarball, run:
tar xjf nextcloud-[version].tar.bz2
unzip nextcloud-[version].zip
3. Stop your Web server.
@ -47,15 +47,21 @@ The other way is by entering your ``config.php`` file and changing
directory to see if they are there. If not, copy them from your old ``apps/``
directory to your new one. Make sure the directory permissions of your third
party application directories are the same as for the other ones.
9. Adjust file ownership and permissions::
9. Restart your Web server.
chown -R www-data:www-data nextcloud
find nextcloud/ -type d -exec chmod 750 {} \;
find nextcloud/ -type f -exec chmod 640 {} \;
10. Now launch the upgrade from the command line using ``occ``, like this
example on CentOS Linux::
10. Restart your Web server.
11. Now launch the upgrade from the command line using ``occ``, like this
example on Ubuntu Linux::
sudo -u apache php occ upgrade
sudo -u www-data php occ upgrade
11. The upgrade operation takes a few minutes to a few hours, depending on the
12. The upgrade operation takes a few minutes to a few hours, depending on the
size of your installation. When it is finished you will see a success
message, or an error message that will tell where it went wrong.
@ -75,11 +81,6 @@ Previous Nextcloud Releases
You'll find previous Nextcloud releases in the `Nextcloud Server Changelog
<https://nextcloud.com/changelog/>`_.
Reverse Upgrade
---------------
If you need to reverse your upgrade, see :doc:`restore`.
Troubleshooting
---------------

60
admin_manual/maintenance/mysql_4byte_support.rst Normal file
View File

@ -0,0 +1,60 @@
=============================
Enabling MySQL 4-byte support
=============================
.. note:: This feature is currently **experimental**.
In order to use Emojis (textbased smilies) on your Nextcloud server with a MySQL database, the
installation needs to be tweaked a bit.
1. Update your Nextcloud server to Nextcloud 11 or later.
2. Make sure the following InnoDB settings are set on your MySQL server::
[mysqld]
innodb_large_prefix=on
innodb_file_format=barracuda
innodb_file_per_table=1
3. Restart the MySQL server in case you changed the configuration in step 2.
4. Change your databases character set and collation::
ALTER DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
5. Set the ``mysql.utf8mb4`` config to true in your config.php::
$ sudo -u www-data occ config:system:set mysql.utf8mb4 --type boolean --value="true"
6. Convert all existing tables to the new collation by running the repair step::
$ sudo -u www-data occ maintenance:repair
Now you should be able to use Emojis in your file names, calendar events, comments and many more.
MariaDB support
===============
.. note:: This is even more **experimental**.
1. Follow MySQL steps 1, 2 and 3
2. Figure out whether the file formate was changed to Barracuda::
MariaDB> SELECT NAME, SPACE, FILE_FORMAT FROM INFORMATION_SCHEMA.INNODB_SYS_TABLES WHERE NAME like "nextcloud%";
If the file format is "Barracuda" for every single table, nothing is left to do. Continue with the MySQL instructions. While testing, all tables' file format was "Antelope".
3. The tables needs to be migrated to "Barracuda" manually, one by one. SQL commands can be created easily, however::
MariaDB> USE INFORMATION_SCHEMA;
MariaDB> SELECT CONCAT("ALTER TABLE `", TABLE_SCHEMA,"`.`", TABLE_NAME, "` ROW_FORMAT=DYNAMIC;") AS MySQLCMD FROM TABLES WHERE TABLE_SCHEMA = "nextcloud";
This will return an SQL command for each table in the nextcloud database. The rows can be quickly copied into a text editor, the "|"s replaced and the SQL commands copied back to the MariaDB shell. If no error appeared (in doubt check step 2) all is done and nothing is left to do here. It can be proceded with the MySQL steps.
4. It is possible, however, that some tables cannot be altered. The operations fails with: "ERROR 1478 (HY000): Table storage engine 'InnoDB' does not support the create option 'ROW_FORMAT'". In that case the failing tables have a SPACE value of 0 in step 2. It basically means that the table does not have an index file of its own, which is required for the Barracuda format. This can be solved with a slightly different SQL command::
MariaDB> ALTER TABLE `nextcloud`.`oc_tablename` ROW_FORMAT=DYNAMIC, ALGORITHM=COPY;
Replace oc_tablename with the failing table. If there are too many (did not happen here), SQL commands can be generated in a batch (task for the reader).
Now everything should be fine and the MySQL instructions should be proceeded.

18
admin_manual/maintenance/package_upgrade.rst
View File

@ -47,9 +47,7 @@ using Snappy Base 16.04 as it's currently unreleased.
* Make a :doc:`fresh backup <backup>`.
* Upgrade your Nextcloud snap: sudo snap refresh nextcloud
* Run :ref:`occ upgrade <command_line_upgrade_label>` (optionally disabling the
:ref:`migration test
<migration_test_label>`).
* Run :ref:`occ upgrade <command_line_upgrade_label>`.
* :ref:`Apply strong permissions <strong_perms_label>` to your
Nextcloud directories.
* Take your Nextcloud server out of :ref:`maintenance mode
@ -81,20 +79,6 @@ This example is for CentOS/RHEL/Fedora::
sudo -u apache php occ upgrade
.. _migration_test_label:
Migration Test
--------------
Before completing the upgrade, Nextcloud first runs a simulation by copying all
database tables to new tables, and then performs the upgrade on them, to ensure
that the upgrade will complete correctly. The copied tables are deleted after
the upgrade. This takes twice as much time, which on large installations can be
many hours, so you can omit this step with the ``--skip-migration-test``
option, like this example on CentOS::
$ sudo -u apache php occ upgrade --skip-migration-test
Setting Strong Directory Permissions
------------------------------------

32
admin_manual/maintenance/restore.rst
View File

@ -30,6 +30,38 @@ install and data folder) to your Nextcloud environment. You could use this comma
Restore Database
----------------
Clean Database Before Restoring
===============================
.. warning:: Before restoring a backup you need to make sure to delete all existing database tables.
The easiest way to do this is to drop and recreate the database.
SQLite does this automatically.
MySQL
^^^^^
MySQL is the recommended database engine. To restore MySQL::
mysql -h [server] -u [username] -p[password] -e "DROP DATABASE nextcloud"
mysql -h [server] -u [username] -p[password] -e "CREATE DATABASE nextcloud"
If you use UTF8 with multibyte support (e.g. for emoijs in filenames), use::
mysql -h [server] -u [username] -p[password] -e "DROP DATABASE nextcloud"
mysql -h [server] -u [username] -p[password] -e "CREATE DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci"
PostgreSQL
^^^^^^^^^^
::
PGPASSWORD="password" psql -h [server] -U [username] -d nextcloud -c "DROP DATABASE \"nextcloud\";"
PGPASSWORD="password" psql -h [server] -U [username] -d nextcloud -c "CREATE DATABASE \"nextcloud\";"
Restoring
=========
.. note:: This guide assumes that your previous backup is called
"nextcloud-sqlbkp.bak"

9
admin_manual/maintenance/update.rst
View File

@ -74,15 +74,6 @@ steps:
This example is for Ubuntu Linux::
$ sudo -u www-data php occ upgrade
Before completing the upgrade, Nextcloud first runs a simulation by copying all
database tables to new tables, and then performs the upgrade on them, to ensure
that the upgrade will complete correctly. The copied tables are deleted after
the upgrade. This takes twice as much time, which on large installations can be
many hours, so you can omit this step with the ``--skip-migration-test``
option, like this example on Ubuntu::
$ sudo -u www-data php occ upgrade --skip-migration-test
See :doc:`../configuration_server/occ_command` to learn more.

9
admin_manual/maintenance/upgrade.rst
View File

@ -4,14 +4,9 @@ How to Upgrade Your Nextcloud Server
There are three ways to upgrade your Nextcloud server:
* Using your :doc:`Linux package manager <package_upgrade>` with our official
Nextcloud repositories. This is the recommended method.
* With the :doc:`Updater App <update>` (Server Edition only). Recommended for
shared hosters, and for users who want an easy way to track different
release channels. (It is not available and not supported on the Enterprise
edition.)
* With the :doc:`Updater App <update>`.
* :doc:`Manually upgrading <manual_upgrade>` with the Nextcloud ``.tar`` archive
from `https://nextcloud.com/install/`_.
from our `Download page <https://nextcloud.com/install/>`_.
* Manually upgrading is also an option for users on shared hosting; download
and unpack the Nextcloud tarball to your PC. Delete your existing Nextcloud
files, except ``data/`` and ``config/`` files, on your hosting account. Then

2
admin_manual/operations/scaling_multiple_machines.rst
View File

@ -28,7 +28,7 @@ structure placing the Nextcloud code in the Apache root directory. The
following components were installed on each application server:
* Apache
* PHP 5.4.x
* PHP 5.6.x
* PHP-GD
* PHP-XML
* PHP-MYSQL

5
admin_manual/operations/theming.rst
View File

@ -6,4 +6,7 @@ Theming Nextcloud
:maxdepth: 2
:hidden:
The theming is documented in the `developers documentation <../../developer_manual/core/theming.html>`_.
Theming can be done very easily using the shipped `theming app <../configuration_server/theming.html>`_, which is enabled by default.
For more individual theming options please head over to the `developers documentation <../../developer_manual/core/theming.html>`_.

2
admin_manual/release_notes.rst
View File

@ -3,7 +3,7 @@ Nextcloud |version| Release Notes
=================================
Changes in 10
Changes in 11
-------------
tbd

7
admin_manual/whats_new_admin.rst
View File

@ -1,7 +0,0 @@
============================================
What's New for Admins in Nextcloud |version|
============================================
See the `Nextcloud 10 Features page
<https://github.com/nextcloud/server/wiki/Nextcloud-10-Features>`_ on Github for a
comprehensive list of new features and updates.

45
developer_manual/app/appdata.rst Normal file
View File

@ -0,0 +1,45 @@
=======
AppData
=======
.. sectionauthor:: Roeland Jago Douma <roeland@famdouma.nl>
Often an app wants to store data. However not all data that is stored belongs with the users files.
Often you just want a very simple storage to have some temp files. In order to facilitate this there
is the AppData folder that provides each app with a private simple filesystem.
Usage is almost trivial when your app is using the AppFramework.
.. code-block:: php
<?php
namespace OCA\MyApp\Controller\MyController;
use OCP\AppFramework\Controller;
use OCP\Files\IAppData;
use OCP\IRequest;
class MyController extends Controller {
/** @var IAppData */
private $appData;
public function __construct($appName,
IRequest $request,
IAppData $appData) {
parent::__construct($appName, $request);
$this->appData = $appData;
}
}
This gives your controller access to the IAppData simple filesystem of your app.
The Simple Filesystem
=====================
The `IAppData` uses the simple filesystem. This is a very simplified filesystem that will allow for easy
mapping to for example memcaches. The filesystem has three elements: `root`, `folder`, `file`.
The `root` can only contain folders. And each folder can only contain files. This is limited to keep
things simple and to allow easy mapping to other backends. For example a sysadmin might chose to map the
avatars to fast storage since they are used often.

2
developer_manual/app/code_signing.rst
View File

@ -118,7 +118,7 @@ examples will assume that you are trying to sign an application named
"contacts".
1. Generate a private key and CSR: ``openssl req -nodes -newkey rsa:2048 -keyout contacts.key -out contacts.csr -subj "/CN=contacts"``. Replace "contacts" with your application identifier.
2. Post the CSR at https://github.com/owncloud/appstore-issues, and configure
2. Post the CSR at https://github.com/nextcloud/app-certificate-requests, and configure
your GitHub account to show your mail address in your profile. Nextcloud
might ask you for further information to verify that you're the legitimate
owner of the application. Make sure to keep the private key file (``contacts.key``)

2
developer_manual/app/container.rst
View File

@ -146,7 +146,7 @@ The container works in the following way:
* The **database connection** is returned from the server container
* Now **AuthorMapper** has all of its dependencies and the object is returned
* **AuthorService** gets the **AuthorMapper** and returns the object
* **AuthorController** gets the **AuthorService** and finally the controller can be ``new``ed and the object is returned
* **AuthorController** gets the **AuthorService** and finally the controller can be instantiated and the object is returned
So basically the container is used as a giant factory to build all the classes that are needed for the application. Because it centralizes all the creation of objects (the **new Class()** lines), it is very easy to add new constructor parameters without breaking existing code: only the **__construct** method and the container line where the **new** is being called need to be changed.

108
developer_manual/app/controllers.rst
View File

@ -653,7 +653,7 @@ OCS
---
.. note:: This is purely for compatibility reasons. If you are planning to offer an external API, go for a :doc:`api` instead.
In order to ease migration from OCS API routes to the App Framework, an additional controller and response have been added. To migrate your API you can use the **OCP\\AppFramework\\OCSController** baseclass and return your data in the form of an array in the following way:
In order to ease migration from OCS API routes to the App Framework, an additional controller and response have been added. To migrate your API you can use the **OCP\\AppFramework\\OCSController** baseclass and return your data in the form of a DataResponse in the following way:
.. code-block:: php
@ -661,6 +661,7 @@ In order to ease migration from OCS API routes to the App Framework, an addition
<?php
namespace OCA\MyApp\Controller;
use OCP\AppFramework\Http\DataResponse;
use OCP\AppFramework\OCSController;
class ShareController extends OCSController {
@ -672,20 +673,34 @@ In order to ease migration from OCS API routes to the App Framework, an addition
* @CORS
*/
public function getShares() {
return [
'data' => [
// actual data is in here
],
// optional
'statuscode' => 100,
'status' => 'OK'
];
return new DataResponse([
//Your data here
]);
}
}
The format parameter works out of the box, no intervention is required.
In order to make routing work for OCS routes you need to add a seperate 'ocs' entry to the routing table of your app.
Inside these are normal routes.
.. code-block:: php
<?php
return [
'ocs' => [
[
'name' => 'Share#getShares',
'url' => '/api/v1/shares',
'verb' => 'GET',
],
],
];
Now your method will be reachable via ``<server>/ocs/v2.php/apps/<APPNAME>/api/v1/shares``
Handling errors
---------------
Sometimes a request should fail, for instance if an author with id 1 is requested but does not exist. In that case use an appropriate `HTTP error code <https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#4xx_Client_Error>`_ to signal the client that an error occurred.
@ -714,9 +729,6 @@ Each response subclass has access to the **setStatus** method which lets you set
}
Authentication
==============
By default every controller method enforces the maximum security, which is:
@ -756,4 +768,76 @@ A controller method that turns off all checks would look like this:
}
Rate limiting
=============
Nextcloud supports rate limiting on a controller method basis. By default controller methods are not rate limited. Rate limiting should be used on expensive or security sensitive functions (e.g. password resets) to increase the overall security of your application.
The native rate limiting will return a 429 status code to clients when the limit is reached and a default Nextcloud error page. When implementing rate limiting in your application, you should thus consider handling error situations where a 429 is returned by Nextcloud.
To enable rate limiting the following *Annotations* can be added to the controller:
* **@UserRateThrottle(limit=int, period=int)**: The rate limiting that is applied to logged-in users. If not specified Nextcloud will fallback to AnonUserRateThrottle.
* **@AnonRateThrottle(limit=int, period=int)**: The rate limiting that is applied to guests.
A controller method that would allow five requests for logged-in users and one request for anonymous users within the last 100 seconds would look as following:
.. code-block:: php
<?php
namespace OCA\MyApp\Controller;
use OCP\IRequest;
use OCP\AppFramework\Controller;
class PageController extends Controller {
/**
* @PublicPage
* @UserRateThrottle(limit=5, period=100)
* @AnonRateThrottle(limit=1, period=100)
*/
public function rateLimitedForAll() {
}
}
Brute-force protection
======================
Nextcloud supports brute-force protection on an action basis. By default controller methods are not protected. Brute-force protection should be used on security sensitive functions (e.g. login attempts) to increase the overall security of your application.
The native brute-force protection will slow down requests if too many violations have been found. This slow down will be applied to all requests against a brute-force protected controller with the same action from the affected IP.
To enable brute force protection the following *Annotation* can be added to the controller:
* **@BruteForceProtection(action=string)**: "string" is the name of the action. Such as "login" or "reset". Brute-force attempts are on a per-action basis; this means if a violation for the "login" action is triggered, other actions such as "reset" or "foobar" are not affected.
Then the **throttle()** method has to be called on the response in case of a violation. Doing so will increase the throttle counter and make following requests slower.
A controller method that would employ brute-force protection with an action of "foobar" would look as following:
.. code-block:: php
<?php
namespace OCA\MyApp\Controller;
use OCP\IRequest;
use OCP\AppFramework\Controller;
use OCP\AppFramework\Http\TemplateResponse;
class PageController extends Controller {
/**
* @BruteForceProtection(action=foobar)
*/
public function rateLimitedForAll() {
$templateResponse = new TemplateResponse(…);
// In case of a violation increase the throttle counter
// note that $this->auth->isSuccessful here is just an
// example.
if(!$this->auth->isSuccessful()) {
$templateResponse->throttle();
}
return $templateResponse;
}
}

19
developer_manual/app/css.rst
View File

@ -132,14 +132,25 @@ To add actions that affect the current list element you can add a menu for secon
</ul>
</div>
<div class="app-navigation-entry-menu open">
<div class="app-navigation-entry-menu">
<ul>
<li><button class="icon-rename svg" title="rename"></button></li>
<li><button class="icon-delete svg" title="delete"></button></li>
<li>
<a href="#" class="menuitem action action-edit permanent">
<span class="icon icon-rename"></span>
<span><?php p($l->t('Edit group'));?></span>
</a>
</li>
<li>
<a href="#" class="menuitem action action-delete permanent">
<span class="icon icon-delete"></span>
<span><?php p($l->t('Delete group'));?></span>
</a>
</li>
</ul>
</div>
</li>
</ul>
</div>
The div with the class **app-navigation-entry-utils** contains only the button (class: **app-navigation-entry-utils-menu-button**) to display the menu but in many cases another entry is needed to display some sort of count (mails count, unread feed count, etc.). In that case add the **with-counter** class to the list entry to adjust the correct padding and text-oveflow of the entry's title.
@ -277,7 +288,7 @@ To create a settings area create a div with the id **app-settings** inside the *
<div id="app-settings-header">
<button class="settings-button"
data-apps-slide-toggle="#app-settings-content"
></button>
><?php p($l->t('Settings'));?></button>
</div>
<div id="app-settings-content">
<!-- Your settings in here -->

6
developer_manual/app/hooks.rst
View File

@ -48,12 +48,13 @@ The hook logic should be in a separate class that is being registered in the :do
<?php
namespace OCA\MyApp\Hooks;
use OCP\IUserManager;
class UserHooks {
private $userManager;
public function __construct($userManager){
public function __construct(IUserManager $userManager){
$this->userManager = $userManager;
}
@ -101,12 +102,13 @@ Hooks available in scope **\\OC\\User**:
* **preSetPassword** (\\OC\\User\\User $user, string $password, string $recoverPassword)
* **postSetPassword** (\\OC\\User\\User $user, string $password, string $recoverPassword)
* **changeUser** (\\OC\\User\\User $user, string $feature, string $value)
* **preDelete** (\\OC\\User\\User $user)
* **postDelete** (\\OC\\User\\User $user)
* **preCreateUser** (string $uid, string $password)
* **postCreateUser** (\\OC\\User\\User $user)
* **preLogin** (string $user, string $password)
* **postLogin** (\\OC\\User\\User $user)
* **postLogin** (\\OC\\User\\User $user, string $password)
* **logout** ()
UserManager

7
developer_manual/app/index.rst
View File

@ -28,6 +28,7 @@
database
configuration
filesystem
appdata
users
two-factor-provider
hooks
@ -136,6 +137,12 @@ Periodically run code in the background:
* :doc:`backgroundjobs`
Settings
---------------
An app can register both admin settings as well as personal settings:
* :doc:`settings`
Logging
-------
Log to the :file:`data/nextcloud.log`:

14
developer_manual/app/info.rst
View File

@ -40,7 +40,7 @@ The :file:`appinfo/info.xml` contains metadata about the app:
<ocsid>1234</ocsid>
<dependencies>
<php min-version="5.4" max-version="5.5"/>
<php min-version="5.6" max-version="7.1"/>
<database>sqlite</database>
<database>mysql</database>
<command os="linux">grep</command>
@ -55,7 +55,7 @@ The :file:`appinfo/info.xml` contains metadata about the app:
<settings>
<admin-section>OCA\YourAppsNamespace\Settings\AdminSection</admin-section>
<admin>OCA\YourAppsNamespace\Settings\AdminSettings</admin>
</setting>
</settings>
<!-- deprecated, just for reference -->
<requiremin>5</requiremin>
@ -88,7 +88,7 @@ description
version
-------
Contains the version of your app. Please also provide the same version in the :file:`appinfo/version`.
Contains the version of your app.
licence
-------
@ -159,7 +159,7 @@ properly. As soon as one of these requirements is not met the app cannot be inst
php
===
Defines the minimum and the maximum version of php which is required to run this app.
Defines the minimum and the maximum version of PHP which is required to run this app.
database
========
@ -170,16 +170,16 @@ In case no database is specified it is assumed that all databases are supported.
command
=======
Defines a command line tool to be available. With the attribute 'os' the required operating system for this tool can be
specified. Valid values for the 'os' attribute are as returned by the php function `php_uname <http://php.net/manual/en/function.php-uname.php>`_.
specified. Valid values for the 'os' attribute are as returned by the PHP function `php_uname <http://php.net/manual/en/function.php-uname.php>`_.
lib
===
Defines a required php extension with required minimum and/or maximum version. The names for the libraries have to match the result as returned by the php function `get_loaded_extensions <http://php.net/manual/en/function.get-loaded-extensions.php>`_.
Defines a required PHP extension with required minimum and/or maximum version. The names for the libraries have to match the result as returned by the PHP function `get_loaded_extensions <http://php.net/manual/en/function.get-loaded-extensions.php>`_.
The explicit version of an extension is read from `phpversion <http://php.net/manual/de/function.phpversion.php>`_ - with some exception as to be read up in the `code base <https://github.com/nextcloud/server/blob/master/lib/private/App/PlatformRepository.php>`_
os
==
Defines the required target operating system the app can run on. Valid values are as returned by the php function `php_uname <http://php.net/manual/en/function.php-uname.php>`_.
Defines the required target operating system the app can run on. Valid values are as returned by the PHP function `php_uname <http://php.net/manual/en/function.php-uname.php>`_.
owncloud
========

2
developer_manual/app/schema.rst
View File

@ -50,4 +50,4 @@ An example database XML file would look like this:
</table>
</database>
To update the tables used by the app, simply adjust the database.xml file and increase the app version number in :file:`appinfo/version` to trigger an update.
To update the tables used by the app, simply adjust the database.xml file and increase the app version number in :file:`appinfo/info.xml` to trigger an update.

13
developer_manual/app/startapp.rst
View File

@ -4,17 +4,11 @@ Create an app
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
After :doc:`you've set up the development environment and installed the dev tool <../general/devenv>` change into the Nextcloud apps directory::
After :doc:`you've set up the development environment <../general/devenv>` change into the Nextcloud apps directory::
cd /var/www/nextcloud/apps
Then run::
ncdev startapp MyApp --email mail@example.com --author "Your Name" --description "My first app" --owncloud 8
This will create all the needed files in the current directory. For more information on how to customize the generated app, see the `Project's GitHub page <https://github.com/nexcloud/ncdev>`_ or run::
ncdev startapp -h
Then create a skeleton app in the `app store <https://apps.nextcloud.com/developer/apps/generate>`_.
Enable the app
--------------
@ -27,7 +21,6 @@ The following directories have now been created:
* **appinfo/**: Contains app metadata and configuration
* **css/**: Contains the CSS
* **js/**: Contains the JavaScript files
* **lib/Controller/**: Contains the controllers
* **lib/**: Contains the other class files of your app
* **lib/**: Contains the php class files of your app
* **templates/**: Contains the templates
* **tests/**: Contains the tests

2
developer_manual/app/templates.rst
View File

@ -64,5 +64,5 @@ To generate links to images use the **image_path** function:
.. code-block:: php
<img src="<?php print_unescaped(image_path('myapp', 'app.png')); ?> />
<img src="<?php print_unescaped(image_path('myapp', 'app.png')); ?>" />

2
developer_manual/app/testing.rst
View File

@ -10,7 +10,7 @@ All PHP classes can be tested with `PHPUnit <http://phpunit.de/>`_, JavaScript c
PHP
===
The PHP tests go into the **tests/** directory. Unfortunately the classloader in core requires a running server (as in fully configured and setup up with a database connection). This is unfortunately too complicated and slow so a separate classloader has to be provided. If the app has been generated with the **ncdev startapp** command, the classloader is already present in the the **tests/** directory and PHPUnit can be run with::
The PHP tests go into the **tests/** directory and PHPUnit can be run with::
phpunit tests/

13
developer_manual/app/theming.rst
View File

@ -21,9 +21,10 @@ When the theming app is enabled, it provides the **OCA.Theming** object. It can
be used to handle themed instances differently.
.. code-block:: javascript
if(OCA.Theming) {
$('.myapp-element').animate({backgroundColor:OCA.Theming.color});
}
if(OCA.Theming) {
$('.myapp-element').animate({backgroundColor:OCA.Theming.color});
}
The following information is available:
@ -33,3 +34,9 @@ The following information is available:
* **OCA.Theming.slogan** Instance slogan
* **OCA.Theming.url** Instance web address
Icons
=====
The theming app will automatically generate favicons and home screen icons for
each app by using the icon `img/app.svg` inside of the app folder. Any custom
favicon set by an app will only be visible when the theming app is disabled.

16
developer_manual/app/tutorial.rst
View File

@ -9,11 +9,12 @@ This tutorial will outline how to create a very simple notes app. The finished a
Setup
=====
After the `development tool <https://github.com/nextcloud/ncdev/blob/master/README.rst#installation>`_ has been installed the :doc:`development environment needs to be set up <../general/devenv>`. This can be done by either `downloading the zip from the website <https://nextcloud.com/install/>`_ or cloning it directly from GitHub::
First the :doc:`development environment <../general/devenv>` needs to be set up. This can be done by either `downloading the zip from the website <https://nextcloud.com/install/>`_ or cloning it directly from GitHub::
ncdev setup core --dir nextcloud --branch $BRANCH
git clone git@github.com:nextcloud/server.git --branch $BRANCH
git submodule update --init
.. note:: $BRANCH is the desired Nextcloud branch (e.g. stable9 for Nextcloud 9, stable10 for Nextcloud 10, etc)
.. note:: ``$BRANCH`` is the desired Nextcloud branch (e.g. ``stable9`` for Nextcloud 9, ``stable10`` for Nextcloud 10, ..., ``master`` for the upcoming release)
First you want to enable debug mode to get proper error messages. To do that set ``debug`` to ``true`` in the **nextcloud/config/config.php** file::
@ -30,14 +31,11 @@ Now open another terminal window and start the development server::
cd nextcloud
php -S localhost:8080
Afterwards the app can be created in the **apps** folder::
Afterwards a skeleton app can be created in the `app store <https://apps.nextcloud.com/developer/apps/generate>`_.
cd apps
ncdev startapp OwnNotes
Download the extracted the downloaded file and move it into your ``apps/`` directory. Afterwards the application can be enabled on the `apps page <http://localhost:8080/index.php/settings/apps>`_.
This creates a new folder called **ownnotes**. Now access and set up Nextcloud through the webinterface at `http://localhost:8080 <http://localhost:8080>`_ and enable the OwnNotes application on the `apps page <http://localhost:8080/index.php/settings/apps>`_.
The first basic app is now available at `http://localhost:8080/index.php/apps/ownnotes/ <http://localhost:8080/index.php/apps/ownnotes/>`_
The first basic app is now available at ``http://localhost:8080/index.php/apps/yourappid/``
Routes & Controllers
====================

2
developer_manual/bugtracker/triaging.rst
View File

@ -108,8 +108,6 @@ An important step of bug triaging is trying to reproduce the bugs, this means, u
This is needed in order to differentiate random/race condition bugs of reproducible ones (which may be reproduced by developers too; and they can fix them).
To reproduce an issue, please refer to our testing documents: :doc:`../testing/index`
If you can't reproduce an issue in a newer version of Nextcloud, it is most likely fixed and can be closed. Comment that you failed to reproduce the problem, and if the reporter can confirm (or doesn't respond for a long time), you can close the issue. Also, be sure to add what exactly you tested with - the Nextcloud Master or a branch (and if so, when), or did you use a release, and if so - what version?
Finalizing and tagging

67
developer_manual/client_apis/OCS/index.rst Normal file
View File

@ -0,0 +1,67 @@
.. _webdavindex:
=========
OCS API's
=========
This document provides a quick overview of the OCS API endpoints supported in Nextcloud.
All requests need to provide authentication information, either as a Basic Auth header or by passing a set of valid session cookies, if not stated otherwise.
----
Testing requests with curl
----
All OCS requests can be easily tested out using :code:`curl` by specifying the request method (:code:`GET`, :code:`PUT`, etc) and setting a request body where needed.
For example: you can perform a :code:`GET` request to get information about a user:
.. code-block:: bash
curl -u username:password -X GET 'https://cloud.example.com/ocs/v1.php/...' -H "OCS-APIRequest: true"
-------------
User metadata
-------------
Since: 11.0.2, 12.0.0
This request returns the available metadata of a user. Admin users can see the information of all users, while a default user only can access it's own metadata.
.. code::
GET /ocs/v1.php/cloud/users/USERID
.. code:: xml
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message>OK</message>
<totalitems></totalitems>
<itemsperpage></itemsperpage>
</meta>
<data>
<enabled>true</enabled>
<quota>
<free>338696790016</free>
<used>7438874</used>
<total>338704228890</total>
<relative>0</relative>
<quota>-3</quota>
</quota>
<email>user@foo.de</email>
<displayname>admin</displayname>
<phone></phone>
<address></address>
<webpage></webpage>
<twitter>schiessle</twitter>
</data>
</ocs>

217
developer_manual/client_apis/WebDAV/index.rst Normal file
View File

@ -0,0 +1,217 @@
.. _webdavindex:
===============================
WebDAV Client API's
===============================
This document provides a quick overview of the WebDAV operations supported in Nextcloud, to keep things readable it won't go into many details
for each operation, further information for each operation can be found in the corresponding rfc where applicable
----
WebDAV Basics
----
The base url for all WebDAV operations for a Nextcloud instance is :code:`/remote.php/dav`.
All requests need to provide authentication information, either as a Basic Auth header or by passing a set of valid session cookies.
----
Testing requests with curl
----
All WebDAV requests can be easily tested out using :code:`curl` by specifying the request method (:code:`GET`, :code:`PROPFIND`, :code:`PUT`, etc) and setting a request body where needed.
For example: you can perform a :code:`PROPFIND` request to find files in a folder using
.. code-block:: bash
curl -u username:password 'https://cloud.example.com/remote.php/dav/files/username/folder' -X PROPFIND --data '<?xml version="1.0" encoding="UTF-8"?>
<d:propfind xmlns:d="DAV:">
<d:prop xmlns:oc="http://owncloud.org/ns">
<d:getlastmodified/>
<d:getcontentlength/>
<d:getcontenttype/>
<oc:permissions/>
<d:resourcetype/>
<d:getetag/>
</d:prop>
</d:propfind>'
----
Listing Folders (rfc4918_)
----
The contents of a folder can be listed by sending a :code:`PROPFIND` request to the folder.
.. code::
PROPFIND remote.php/dav/files/user/path/to/folder
~~~~
Requesting properties
~~~~
By default, a :code:`PROPFIND` request will only return a small number of properties for each file: last modified date, file size, whether it's a folder, etag and mime type.
You can request additional properties by sending a request body with the :code:`PROPFIND` request that lists all requested properties.
.. code-block:: xml
<?xml version="1.0"?>
<d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
<d:prop>
<d:getlastmodified />
<d:getetag />
<d:getcontenttype />
<d:resourcetype />
<oc:fileid />
<oc:permissions />
<oc:size />
<d:getcontentlength />
<nc:has-preview />
<oc:favorite />
<oc:comments-unread />
<oc:owner-display-name />
<oc:share-types />
</d:prop>
</d:propfind>
The following properties are supported:
- :code:`{DAV:}getlastmodified`
- :code:`{DAV:}getetag`
- :code:`{DAV:}getcontenttype`
- :code:`{DAV:}resourcetype`
- :code:`{DAV:}getcontentlength`
- :code:`{http://owncloud.org/ns}id` The fileid namespaced by the instance id, globally unique
- :code:`{http://owncloud.org/ns}fileid` The unique id for the file within the instance
- :code:`{http://owncloud.org/ns}favorite`
- :code:`{http://owncloud.org/ns}comments-href`
- :code:`{http://owncloud.org/ns}comments-count`
- :code:`{http://owncloud.org/ns}comments-unread`
- :code:`{http://owncloud.org/ns}owner-id` The user id of the owner of a shared file
- :code:`{http://owncloud.org/ns}owner-display-name` The display name of the owner of a shared file
- :code:`{http://owncloud.org/ns}share-types`
- :code:`{http://owncloud.org/ns}checksums`
- :code:`{http://owncloud.org/ns}has-preview`
- :code:`{http://owncloud.org/ns}size` Unlike :code:`getcontentlength`, this property also works for folders reporting the size of everything in the folder.
~~~~
Getting properties for just the folder
~~~~
You can request properties of a folder without also getting the folder contents by adding a :code:`Depth: 0` header to the request.
----
Downloading files
----
A file can be downloaded by sending a :code:`GET` request to the WebDAV url of the file.
.. code::
GET remote.php/dav/files/user/path/to/file
----
Uploading files
----
A file can be uploading by sending a :code:`PUT` request to the file and sending the raw file contents as the request body.
.. code::
PUT remote.php/dav/files/user/path/to/file
Any existing file will be overwritten by the request.
----
Creating folders (rfc4918_)
----
A folder can be created by sending a :code:`MKCOL` request to the folder.
.. code::
MKCOL remote.php/dav/files/user/path/to/new/folder
----
Deleting files and folders (rfc4918_)
----
A file or folder can be created by sending a :code:`DELETE` request to the file or folder.
.. code::
DELETE remote.php/dav/files/user/path/to/file
When deleting a folder, it's contents will be deleted recursively.
----
Moving files and folders (rfc4918_)
----
A file or folder can be moved by sending a :code:`MOVE` request to the file or folder and specifying the destination in the :code:`Destination` header as full url.
.. code::
MOVE remote.php/dav/files/user/path/to/file
Destination: https://cloud.example/remote.php/dav/files/user/new/location
The overwrite behavior of the move can be controlled by setting the :code:`Overwrite` head to :code:`T` or :code:`F` to enable or disable overwriting respectively.
----
Copying files and folders (rfc4918_)
----
A file or folder can be copied by sending a :code:`COPY` request to the file or folder and specifying the destination in the :code:`Destination` header as full url.
.. code::
COPY remote.php/dav/files/user/path/to/file
Destination: https://cloud.example/remote.php/dav/files/user/new/location
The overwrite behavior of the copy can be controlled by setting the :code:`Overwrite` head to :code:`T` or :code:`F` to enable or disable overwriting respectively.
----
Settings favorites
----
A file or folder can be marked as favorite by sending a :code:`PROPPATCH` request to the file or folder and setting the :code:`oc-favorite` property
.. code-block:: xml
PROPPATCH remote.php/dav/files/user/path/to/file
<?xml version="1.0"?>
<d:propertyupdate xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns">
<d:set>
<d:prop>
<oc:favorite>1</oc:favorite>
</d:prop>
</d:set>
</d:propertyupdate>
Setting the :code:`oc:favorite` property to 1 marks a file as favorite, setting it to 0 un-marks it as favorite.
----
Listing favorites
----
Favorites for a user can be retrieved by sending a :code:`REPORT` request and specifying :code:`oc:favorite` as a filter
.. code-block:: xml
REPORT remote.php/dav/files/user/path/to/folder
<?xml version="1.0"?>
<oc:filter-files xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns">
<oc:filter-rules>
<oc:favorite>1</oc:favorite>
</oc:filter-rules>
</oc:filter-files>
File properties can be requested by adding a :code:`<d:prop/>` element to the request listing the requested properties in the same way as it would be done for a :code:`PROPFIND` request.
When listing favorites, the request will find all favorites in the folder recursively, all favorites for a user can be found by sending the request to :code:`remote.php/dav/files/user`
.. _rfc4918: https://tools.ietf.org/html/rfc4918

35
developer_manual/client_apis/index.rst Normal file
View File

@ -0,0 +1,35 @@
.. _apiindex:
===============================
Client API's
===============================
Nextcloud provides an number of api's for client applications to talk to.
----
WebDAV
----
WebDAV is the main api for file related operations, it supports listing directories, downloading an uploading files, manipulating tags and favorites and more.
An overview of how to use the various WebDAV api's can be found at :doc:`WebDAV/index`
---
OCS
---
The OCS API provides all information that are not available via the DAV endpoints. This contains endpoints for user data or sharing capabilities for example. See :doc:`OCS/index` for more details.
Other OCS API documentations:
* `Notifications API <https://github.com/nextcloud/notifications/blob/master/docs/ocs-endpoint-v2.md>`_
* `Notifications API - Register a device for push notifications <https://github.com/nextcloud/notifications/blob/5a2d3607952bad675e4057620a9c7de8a7f84f0b/docs/push-v3.md>`_
.. toctree::
:maxdepth: 2
:hidden:
webdav/index
ocs/index

34
developer_manual/conf.py
View File

@ -40,17 +40,17 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'ownCloud Developer Manual'
copyright = u'2012-2015, The ownCloud developers'
project = u'Nextcloud Developer Manual'
copyright = u'2012-2016, The Nextcloud developers'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '9.1'
version = '11'
# The full version, including alpha/beta/rc tags.
release = '9.1'
release = '11 alpha'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
@ -166,7 +166,7 @@ html_show_sphinx = False
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'owncloudDeveloperManual'
htmlhelp_basename = 'NextcloudDeveloperManual'
# -- Options for LaTeX output --------------------------------------------------
@ -185,8 +185,8 @@ latex_elements = {
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'ownCloudDeveloperManual.tex', u'ownCloud Developer Manual',
u'The ownCloud developers', 'manual'),
('index', 'NextcloudDeveloperManual.tex', u'Nextcloud Developer Manual',
u'The Nextcloud developers', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
@ -211,16 +211,16 @@ latex_logo = '../_shared_assets/static/logo-blue.pdf'
# -- Options for pdf page output -----------------------------------------------
pdf_documents = [('index', u'owncloudDeveloperManual', u'ownCloud Developer Manual',
u'The ownCloud developers'),]
pdf_documents = [('index', u'NextcloudDeveloperManual', u'Nextcloud Developer Manual',
u'The Nextcloud developers'),]
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'owncloudDeveloperManual', u'ownCloud Developer Manual',
[u'The ownCloud developers'], 1)
('index', 'NextcloudDeveloperManual', u'Nextcloud Developer Manual',
[u'The Nextcloud developers'], 1)
]
# If true, show URL addresses after external links.
@ -233,8 +233,8 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'ownCloudDeveloperManual', u'ownCloud Developer Manual',
u'The ownCloud developers', 'ownCloud', 'The ownCloud Developer Manual.',
('index', 'NextcloudDeveloperManual', u'Nextcloud Developer Manual',
u'The Nextcloud developers', 'Nextcloud', 'The Nextcloud Developer Manual.',
'Miscellaneous'),
]
@ -251,10 +251,10 @@ texinfo_documents = [
# -- Options for Epub output ---------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = u'ownCloud Developer Manual'
epub_author = u'The ownCloud developers'
epub_publisher = u'The ownCloud developers'
epub_copyright = u'2012-2015, The ownCloud developers'
epub_title = u'Nextcloud Developer Manual'
epub_author = u'The Nextcloud developers'
epub_publisher = u'The Nextcloud developers'
epub_copyright = u'2012-2016, The Nextcloud developers'
# The language of the text. It defaults to the language option
# or en if the language is not set.

2
developer_manual/core/ocs-share-api.rst
View File

@ -7,6 +7,8 @@ pre-defined OCS calls.
The base URL for all calls to the share API is: *<nextcloud_base_url>/ocs/v1.php/apps/files_sharing/api/v1*
All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``.
Local Shares
============

1
developer_manual/core/theming.rst
View File

@ -37,6 +37,7 @@ Depending on how you created your new theme it will be necessary to
* put a new theme into the /themes -folder. The theme can be activated by putting ``'theme' => 'MyTheme'``, into the ``/config/config.php`` file.
* make your changes in the ``/themes/MyTheme`` -folder
* make sure that the theming app is disabled
Structure

8
developer_manual/general/backporting.rst
View File

@ -14,10 +14,10 @@ Process
We mostly consider bug fixes for back porting. Occasionally, important changes to the API can be backported to make it easier for developers to keep their apps working between major releases. If you think a pull request (PR) is relevant for the stable release, go through these steps:
1. Make sure the PR is merged to master
2. Ask Frank (**@karlitschek**) and Thomas (**@deepdiver1975**) if the code should be backported and add the label `backport-request <https://github.com/nextcloud/server/labels/backport-request>`_ to the PR
3. If Frank or Thomas say yes then create a new branch based on the respective stable branch (stable7 for the 7.0.x series), cherry-pick the needed commits to that branch and create a PR on GitHub.
4. Specify the corresponding milestone for that series (7.0.x-next-maintenance for the 7.0.x series) to this PR and reference the original PR in there. This enables the QA team to find the backported items for testing and having the original PR with detailed description linked.
2. Ask Frank (**@karlitschek**), if the code should be backported and add the label `backport-request <https://github.com/nextcloud/server/labels/backport-request>`_ to the PR
3. If Frank approves, create a new branch based on the respective stable branch (stable10 for the 10.0.x series), cherry-pick the needed commits to that branch and create a PR on GitHub.
4. Specify the corresponding milestone for that series (10.0.x-next-maintenance for the 10.0.x series) to this PR and reference the original PR in there. This enables the QA team to find the backported items for testing and having the original PR with detailed description linked.
.. note:: Before each patch release there is a freeze to be able to test everything as a whole without pulling in new changes. This freeze is announced on the `owncloud-devel mailinglist <https://mailman.owncloud.org/pipermail/devel/>`_. While this freeze is active a backport isn't allowed and has to wait for the next patch release.
.. note:: Before each patch release there is a freeze to be able to test everything as a whole without pulling in new changes. While this freeze is active a backport isn't allowed and has to wait for the next patch release.
The QA team will try to reproduce all the issues with the X.Y.Z-next-maintenance milestone on the relevant release and verify it is fixed by the patch release (and doesn't cause new problems). Once the patch release is out, the post-fix -next-maintenance is removed and a new -next-maintenance milestone is created for that series.

6
developer_manual/general/devenv.rst
View File

@ -48,15 +48,15 @@ Check out the code
The following commands are using **/var/www** as the Web server's directory and **www-data** as user name and group.
Install the `development tool <https://github.com/nextcloud/ncdev>`_
After the development tool installation make the directory writable::
sudo chmod o+rw /var/www
Then install Nextcloud from git::
ncdev setup --dir /var/www/<folder> server
git clone git@github.com:nextcloud/server.git /var/www/<folder>
cd /var/www/<folder>
git submodule update --init
where <folder> is the folder where you want to install Nextcloud.

2
developer_manual/general/security.rst
View File

@ -246,4 +246,4 @@ Always validate the URL before redirecting if the requested URL is on the same d
Getting help
------------
If you need help to ensure that a function is secure please ask on our `mailing list <https://mailman.owncloud.org/mailman/listinfo/devel>`_ or on our IRC channel **#nextcloud-dev** on **irc.freenode.net**.
If you need help to ensure that a function is secure please ask on our `forum <https://help.nextcloud.com>`_ or on our IRC channel **#nextcloud-dev** on **irc.freenode.net**.

1
developer_manual/index.rst
View File

@ -17,6 +17,7 @@ Table of Contents
general/index
app/index
android_library/index
client_apis/index
core/index
bugtracker/index
commun/index

Some files were not shown because too many files have changed in this diff Show More