diff --git a/.drone.yml b/.drone.yml index edde62951..41bce2d7e 100644 --- a/.drone.yml +++ b/.drone.yml @@ -2,7 +2,4 @@ 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) + - make all diff --git a/README.rst b/README.rst index bad93d367..9f494fb5c 100644 --- a/README.rst +++ b/README.rst @@ -13,13 +13,13 @@ See the `Style Guide
{% if theme_show_search %} -
+
@@ -191,13 +191,14 @@

Follow us on Google Plus! - Like our facebook page! - Subscribe to our twitter channel! + Like our Facebook page! + Subscribe to our Twitter channel! Subscribe to our news feed! Subscribe to our newsletter!

- All documentation licensed under the Creative Commons Attribution 3.0 Unported license. +

All documentation licensed under the Creative Commons Attribution 3.0 Unported license.

+

See who contributed to our documentation/credits.

diff --git a/_shared_assets/themes/nextcloud_com/static/styles.css b/_shared_assets/themes/nextcloud_com/static/styles.css index 408ccee6d..1daa423f6 100644 --- a/_shared_assets/themes/nextcloud_com/static/styles.css +++ b/_shared_assets/themes/nextcloud_com/static/styles.css @@ -1080,6 +1080,8 @@ h4:hover a.headerlink { } a.headerlink { display: none; + padding-left: 5px; + text-decoration: none; } #menu-support { @@ -1130,4 +1132,9 @@ a.headerlink { between above the top of the third level list */ #menu-support.menu ul ul ul { border-top: 1px solid #EFEFEF; -} \ No newline at end of file +} + +.terminal-image { + box-shadow: 1px 1px 15px rgba(0, 0, 0, 0.3); + border-radius: 2px; +} diff --git a/_shared_assets/themes/nextcloud_release/static/styles.css b/_shared_assets/themes/nextcloud_release/static/styles.css index f7dac96ce..40015cd84 100644 --- a/_shared_assets/themes/nextcloud_release/static/styles.css +++ b/_shared_assets/themes/nextcloud_release/static/styles.css @@ -474,3 +474,8 @@ li.next { } /* -- End specific css for documentation -- */ + +.terminal-image { + box-shadow: 1px 1px 15px rgba(0, 0, 0, 0.3); + border-radius: 2px; +} diff --git a/admin_manual/conf.py b/admin_manual/conf.py index cf07264e8..d6f79f5b1 100644 --- a/admin_manual/conf.py +++ b/admin_manual/conf.py @@ -44,13 +44,13 @@ master_doc = 'contents' # built documents. # # The short X.Y version. -version = '11' +version = '12' # The full version, including alpha/beta/rc tags. -release = '11 alpha' +release = '12' # General information about the project. project = u'Nextcloud %s Server Administration Manual' % (version) -copyright = u'2012-2016, The Nextcloud developers' +copyright = u'2012-2017, The Nextcloud developers' # The language for content autogenerated by Sphinx. Refer to documentation @@ -244,7 +244,7 @@ texinfo_documents = [ ('contents', 'Nextcloud Server Admin Manual', u'Nextcloud 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' +epub_copyright = u'2012-2017, The Nextcloud developers' # The language of the text. It defaults to the language option # or en if the language is not set. diff --git a/admin_manual/configuration_database/index.rst b/admin_manual/configuration_database/index.rst index 492d92ca8..202ee1ae4 100644 --- a/admin_manual/configuration_database/index.rst +++ b/admin_manual/configuration_database/index.rst @@ -7,3 +7,4 @@ Database Configuration db_conversion.rst linux_database_configuration.rst + mysql_4byte_support diff --git a/admin_manual/configuration_database/linux_database_configuration.rst b/admin_manual/configuration_database/linux_database_configuration.rst index 2f7ed64d0..2d1935210 100644 --- a/admin_manual/configuration_database/linux_database_configuration.rst +++ b/admin_manual/configuration_database/linux_database_configuration.rst @@ -20,37 +20,6 @@ requires that you install and set up the server software first. scope of this document. Please refer to the documentation for your specific database choice for instructions. -.. _db-binlog-label: - -MySQL / MariaDB with Binary Logging Enabled -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Nextcloud is currently using a ``TRANSACTION_READ_COMMITTED`` transaction isolation -to avoid data loss under high load scenarios (e.g. by using the sync client with -many clients/users and many parallel operations). This requires a disabled or -correctly configured binary logging when using MySQL or MariaDB. Your system is -affected if you see the following in your log file during the installation or -update of Nextcloud: - - An unhandled exception has been thrown: - exception 'PDOException' with message 'SQLSTATE[HY000]: General error: 1665 - Cannot execute statement: impossible to write to binary log since - BINLOG_FORMAT = STATEMENT and at least one table uses a storage engine limited - to row-based logging. InnoDB is limited to row-logging when transaction - isolation level is READ COMMITTED or READ UNCOMMITTED.' - -There are two solutions. One is to disable binary logging. Binary logging -records all changes to your database, and how long each change took. The -purpose of binary logging is to enable replication and to support backup -operations. - -The other is to change the BINLOG_FORMAT = STATEMENT in your database -configuration file, or possibly in your database startup script, to -BINLOG_FORMAT = MIXED. See `Overview of the Binary -Log `_ and `The -Binary Log `_ for -detailed information. - .. _db-transaction-label: Database "READ COMMITED" transaction isolation level @@ -176,7 +145,7 @@ You can quit the prompt by entering:: 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, -and an empty password to access it, and the name of the database. The :file:`config/config.php` as +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: @@ -240,9 +209,9 @@ Troubleshooting How to workaround General error: 2006 MySQL server has gone away ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The database request takes too long and therefore the MySQL server times out. Its -also possible that the server is dropping a packet that is too large. Please -refer to the manual of your database for how to raise the configuration options +The database request takes too long and therefore the MySQL server times out. Its +also possible that the server is dropping a packet that is too large. Please +refer to the manual of your database for how to raise the configuration options ``wait_timeout`` and/or ``max_allowed_packet``. Some shared hosters are not allowing the access to these config options. For such diff --git a/admin_manual/maintenance/mysql_4byte_support.rst b/admin_manual/configuration_database/mysql_4byte_support.rst similarity index 97% rename from admin_manual/maintenance/mysql_4byte_support.rst rename to admin_manual/configuration_database/mysql_4byte_support.rst index d6f44bcaf..d90a74eb4 100644 --- a/admin_manual/maintenance/mysql_4byte_support.rst +++ b/admin_manual/configuration_database/mysql_4byte_support.rst @@ -2,8 +2,6 @@ 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. @@ -11,7 +9,7 @@ installation needs to be tweaked a bit. 2. Make sure the following InnoDB settings are set on your MySQL server:: [mysqld] - innodb_large_prefix=on + innodb_large_prefix=true innodb_file_format=barracuda innodb_file_per_table=1 diff --git a/admin_manual/configuration_files/big_file_upload_configuration.rst b/admin_manual/configuration_files/big_file_upload_configuration.rst index bd0ef564d..778c22b0a 100644 --- a/admin_manual/configuration_files/big_file_upload_configuration.rst +++ b/admin_manual/configuration_files/big_file_upload_configuration.rst @@ -7,8 +7,6 @@ limit up to what your filesystem and operating system allows. There are certain hard limits that cannot be exceeded: * < 2GB on 32Bit OS-architecture -* < 2GB on Windows (32Bit and 64Bit) -* < 2GB with Server Version 4.5 or older * < 2GB with IE6 - IE8 * < 4GB with IE9 - IE11 @@ -82,7 +80,7 @@ nginx * `client_body_temp_path `_ Since nginx 1.7.11 a new config option `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. @@ -162,7 +160,4 @@ To be able to use this input box you need to make sure that: * 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 -to decide between the ability to use the input box and a more secure Nextcloud installation -where you need to manually modify the upload limits in the ``.htaccess`` and ``.user.ini`` -files described above. + diff --git a/admin_manual/configuration_files/default_files_configuration.rst b/admin_manual/configuration_files/default_files_configuration.rst index 372e6aec3..95cba178e 100644 --- a/admin_manual/configuration_files/default_files_configuration.rst +++ b/admin_manual/configuration_files/default_files_configuration.rst @@ -2,15 +2,21 @@ Providing Default Files ======================= -You may distribute a set of default files and folders to all users by placing -them in the :file:`nextcloud/core/skeleton` directory on your Nextcloud server. -These files appear only to new users after their initial login, and existing -users will not see files that are added to this directory after their first -login. The files in the :file:`skeleton` directory are copied into the users' -data directories, so they may change and delete the files without affecting the -originals. +You may distribute a set of default files and folders to all users by placing +them in directory that is readable by the webserver user. This allows you to +overwrite the files that are shipped by default with Nextcloud in +``core/skeleton``. That custom directory should then be configured in the +``config.php`` via the configuration option ``skeletondirectory`` (see +:doc:`../configuration_server/config_sample_php_parameters`). Leave +empty to not copy any skeleton files. -This screenshot shows a set of photos in the :file:`skeleton` directory. +These files will be copied only to new users after their initial login, and +existing users will not see files that are added to this directory after their +first login. The files in the ``skeleton`` directory are copied into the +users data directories, so they may change and delete the files without +affecting the originals. + +This screenshot shows a set of photos in the ``skeleton`` directory. .. image:: ../images/skeleton-files.png @@ -18,12 +24,6 @@ They appear on the user's Nextcloud Files page just like any other files. .. image:: ../images/skeleton-files1.png -Additional Configuration ------------------------- - -The configuration option ``skeletondirectory`` available in your -``config.php`` (See -:doc:`../configuration_server/config_sample_php_parameters`) allows -you to configure 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. \ No newline at end of file +.. note:: Overwriting the files in ``core/skeleton`` is not recommended, + because those changes will be overwritten on the next update of the Nextcloud + server. \ No newline at end of file diff --git a/admin_manual/configuration_files/encryption_configuration.rst b/admin_manual/configuration_files/encryption_configuration.rst index c0cbd00dc..aeeeffe60 100644 --- a/admin_manual/configuration_files/encryption_configuration.rst +++ b/admin_manual/configuration_files/encryption_configuration.rst @@ -146,7 +146,7 @@ storage mount, see :ref:`external_storage_mount_options_label` .. _enable-file-recovery-key: Enabling Users File Recovery Keys ----------------------------------- +--------------------------------- If you lose your Nextcloud password, then you lose access to your encrypted files. If one of your users loses their Nextcloud password their files are @@ -213,11 +213,11 @@ The [module ID] is taken from the ``encryption:list-modules`` command. Encrypt all data files for all users. For performance reasons, when you enable encryption on an Nextcloud server only new and changed files are encrypted. This 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 +Nextcloud server into maintenance mode to prevent any user activity until encryption is completed:: - occ maintenance:singleuser --on - Single user mode is currently enabled + occ maintenance:mode --on + Maintenance mode is currently enabled Then run ``occ``:: @@ -267,14 +267,14 @@ Disabling Encryption You may disable encryption only with ``occ``. Make sure you have backups of all encryption keys, including users'. Put your Nextcloud server into -single-user mode, and then disable your encryption module with this command:: +maintenance mode, and then disable your encryption module with this command:: - occ maintenance:singleuser --on + occ maintenance:mode --on occ encryption:disable -Take it out of single-user mode when you are finished:: +Take it out of maintenance mode when you are finished:: - occ maintenance:singleuser --off + occ maintenance:mode --off Files Not Encrypted ------------------- diff --git a/admin_manual/configuration_files/external_storage/local.rst b/admin_manual/configuration_files/external_storage/local.rst index 32e241076..ff2b85cb3 100644 --- a/admin_manual/configuration_files/external_storage/local.rst +++ b/admin_manual/configuration_files/external_storage/local.rst @@ -15,9 +15,6 @@ are on Ubuntu Linux:: sudo -u www-data chown -R www-data:www-data /localdir sudo -u www-data chmod -R 0750 /localdir -See :ref:`strong_perms_label` for information on correct file permissions, and -find your HTTP user :ref:`label-phpinfo`. - In the **Folder name** field enter the folder name that you want to appear on your Nextcloud Files page. diff --git a/admin_manual/configuration_files/index.rst b/admin_manual/configuration_files/index.rst index 1e4612f09..b20264ee5 100644 --- a/admin_manual/configuration_files/index.rst +++ b/admin_manual/configuration_files/index.rst @@ -18,4 +18,3 @@ File Sharing and Management files_locking_transactional previews_configuration file_versioning - files_access_control diff --git a/admin_manual/configuration_server/activity_configuration.rst b/admin_manual/configuration_server/activity_configuration.rst index dbbb034de..803377935 100644 --- a/admin_manual/configuration_server/activity_configuration.rst +++ b/admin_manual/configuration_server/activity_configuration.rst @@ -30,3 +30,26 @@ 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. + +Better scheduling of activity emails +------------------------------------ + +In certain scenarios it makes sense to send the activity emails out more regularly, +e.g. you want to send the hourly emails always at the full hour, daily emails before +people start to work in the morning and weekly mails shall be send on monday morning, +so people can read up when starting into the week. + +Therefor in Nextcloud 12 a console command was added to allow sending those emails +intentionally. This allows to set up special cron jobs on your server with the known +granularity, instead of relying on the Nextcloud cron feature which is not very flexible +on scheduling. + +To implement the samples mentioned above, the following three entries are necessary:: + + # crontab -u www-data -e + 0 * * * * php -f /var/www/nextcloud/occ activity:send-mails hourly + 30 7 * * * php -f /var/www/nextcloud/occ activity:send-mails daily + 30 7 * * MON php -f /var/www/nextcloud/occ activity:send-mails weekly + +If you want to manually send out all activity emails which are queued, you can run +``occ activity:send-mails`` without any argument. diff --git a/admin_manual/configuration_server/background_jobs_configuration.rst b/admin_manual/configuration_server/background_jobs_configuration.rst index ca4cb1faa..5128e8bd7 100644 --- a/admin_manual/configuration_server/background_jobs_configuration.rst +++ b/admin_manual/configuration_server/background_jobs_configuration.rst @@ -83,3 +83,46 @@ You can verify if the cron job has been added and scheduled by executing:: .. note:: Please refer to the crontab man page for the exact command syntax. .. _easyCron: http://www.easycron.com/ + +systemd +~~~~~~~ + +If systemd is installed on the system, a systemd timer could be an alternative to a cronjob. + +This approach requires two files: **nextcloudcron.service** and **nextcloudcron.timer**. Create these two files in ``/etc/systemd/system/``. + +**nextcloudcron.service** should look like this:: + + [Unit] + Description=Nextcloud cron.php job + + [Service] + User=www-data + ExecStart=/usr/bin/php -f /var/www/nextcloud/cron.php + + [Install] + WantedBy=basic.target + +Replace the user ``www-data`` with the user of your http server and ``/var/www/nextcloud/cron.php`` with the location of **cron.php** in your nextcloud directory. + +**nextcloudcron.timer** should look like this:: + + [Unit] + Description=Run Nextcloud cron.php every 15 minutes + + [Timer] + OnBootSec=5min + OnUnitActiveSec=15min + Unit=nextcloudcron.service + + [Install] + WantedBy=timers.target + +The important parts in the timer-unit are ``OnBootSec`` and ``OnUnitActiveSec``.``OnBootSec`` will start the timer 5 minutes after boot, otherwise you would have to start it manually after every boot. ``OnUnitActiveSec`` will set a 15 minute timer after the service-unit was last activated. + +Now all that is left is to start and enable the timer by running these commands:: + + systemctl start nextcloudcron.timer + systemctl enable nextcloudcron.timer + +.. note:: Select the option ``Cron`` in the admin menu for background jobs. if left on ``AJAX`` it would execute the AJAX job on every page load. diff --git a/admin_manual/configuration_server/caching_configuration.rst b/admin_manual/configuration_server/caching_configuration.rst index be726530e..0bc9d50d6 100644 --- a/admin_manual/configuration_server/caching_configuration.rst +++ b/admin_manual/configuration_server/caching_configuration.rst @@ -46,7 +46,7 @@ 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 install -``php-pecl-apcu``. On Debian/Ubuntu/Mint systems install ``php5-apcu`` or ``php7.0-apcu``. +``php-pecl-apcu``. On Debian/Ubuntu/Mint systems install ``php-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:: @@ -113,7 +113,7 @@ 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`` or ``php7.0-redis``. The installer +On Debian/Ubuntu/Mint install ``redis-server`` and ``php-redis``. The installer will automatically launch ``redis-server`` and configure it to launch at startup. diff --git a/admin_manual/configuration_server/config_sample_php_parameters.rst b/admin_manual/configuration_server/config_sample_php_parameters.rst index e6d92fb8b..4ad601a6c 100644 --- a/admin_manual/configuration_server/config_sample_php_parameters.rst +++ b/admin_manual/configuration_server/config_sample_php_parameters.rst @@ -228,6 +228,18 @@ language" override this setting after they have logged in. Defaults to ``en`` +:: + + 'force_language' => 'en', + +With this setting a language can be forced for all users. If a language is +forced, the users are also unable to change their language in the personal +settings. If users shall be unable to change their language, but users have +different languages, this value can be set to ``true`` instead of a language +code. + +Defaults to ``false`` + :: 'defaultapp' => 'files', @@ -247,16 +259,6 @@ Defaults to ``files`` ``true`` enables the Help menu item in the user menu (top right of the Nextcloud Web interface). ``false`` removes the Help item. -:: - - 'enable_avatars' => true, - -``true`` enables avatars, or user profile photos. These appear on the User -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, @@ -338,11 +340,13 @@ IMAP (OC_User_IMAP), SMB (OC_User_SMB), and FTP (OC_User_FTP). 'lost_password_link' => 'https://example.org/link/to/password/reset', -If your user backend does not allow to reset the password (e.g. when it's a +If your user backend does not allow password resets (e.g. when it's a read-only user backend like LDAP), you can specify a custom link, where the user is redirected to, when clicking the "reset password" link after a failed login-attempt. +In case you do not want to provide any link, replace the url with 'disabled' + Mail Parameters --------------- @@ -543,12 +547,12 @@ accessible at. So if Nextcloud is accessible via "https://mycloud.org/nextcloud" the correct value would most likely be "/nextcloud". If Nextcloud is running under "https://mycloud.org/" then it would be "/". -Note that above rule is not valid in every case, there are some rare setup +Note that the above rule is not valid in every case, as there are some rare setup cases where this may not apply. However, to avoid any update problems this configuration value is explicitly opt-in. -After setting this value run `occ maintenance:update:htaccess` and when following -conditions are met Nextcloud uses URLs without index.php in it: +After setting this value run `occ maintenance:update:htaccess`. Now, when the +following conditions are met Nextcloud URLs won't contain `index.php`: - `mod_rewrite` is installed - `mod_env` is installed @@ -859,14 +863,6 @@ Defaults to ``UTC`` Append all database queries and parameters to the log file. Use this only for debugging, as your logfile will become huge. -:: - - 'cron_log' => true, - -Log successful cron runs. - -Defaults to ``true`` - :: 'log_rotate_size' => false, @@ -1059,10 +1055,6 @@ concerns: - OC\\Preview\\TIFF - OC\\Preview\\Font -.. note:: Troubleshooting steps for the MS Word previews are available - at the :doc:`../configuration_files/collaborative_documents_configuration` - section of the Administrators Manual. - The following providers are not available in Microsoft Windows: - OC\\Preview\\Movie @@ -1101,6 +1093,14 @@ See command line (occ) methods ``ldap:show-remnants`` and ``user:delete`` Defaults to ``51`` minutes +:: + + 'sort_groups_by_name' => false, + +Sort groups in the user settings by name instead of the user count + +By enabling this the user count beside the group name is disabled as well. + Comments -------- @@ -1123,10 +1123,19 @@ Defaults to ``\OC\Comments\ManagerFactory`` 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. +filesystem instead of the database to keep the tags. Defaults to ``\OC\SystemTag\ManagerFactory`` +:: + + 'mail_template_class' => '\OC\Mail\EMailTemplate', + +Replaces the default mail template layout. This can be utilized if the +options to modify the mail texts with the theming app is not enough. + +The class must extend ``\OC\Mail\EMailTemplate`` + Maintenance ----------- @@ -1147,15 +1156,6 @@ are kicked out of Nextcloud instantly. Defaults to ``false`` -:: - - 'singleuser' => false, - -When set to ``true``, the Nextcloud instance will be unavailable for all -users who are not in the ``admin`` group. - -Defaults to ``false`` - SSL --- @@ -1170,12 +1170,6 @@ Extra SSL options to be used for configuration. Defaults to an empty array. -:: - - 'enable_certificate_management' => false, - -Allow the configuration of system wide trusted certificates - Memory caching backend configuration ------------------------------------ @@ -1218,20 +1212,53 @@ Defaults to ``none`` :: - 'redis' => array( + 'redis' => [ 'host' => 'localhost', // can also be a unix domain socket: '/tmp/redis.sock' 'port' => 6379, 'timeout' => 0.0, 'password' => '', // Optional, if not defined no password will be used. 'dbindex' => 0, // Optional, if undefined SELECT will not run and will use Redis Server's default DB Index. - ), + ], -Connection details for redis to use for memory caching. +Connection details for redis to use for memory caching in a single server configuration. For enhanced security it is recommended to configure Redis to require a password. See http://redis.io/topics/security for more information. +:: + + 'redis.cluster' => [ + 'seeds' => [ // provide some/all of the cluster servers to bootstrap discovery, port required + 'localhost:7000', + 'localhost:7001' + ], + 'timeout' => 0.0, + 'read_timeout' => 0.0, + 'failover_mode' => \RedisCluster::FAILOVER_ERROR + ], + +Connection details for a Redis Cluster + +Only for use with Redis Clustering, for Sentinel-based setups use the single +server configuration above, and perform HA on the hostname. + +Redis Cluster support requires the php module phpredis in version 3.0.0 or +higher for PHP 7+ or phpredis in version 2.2.8 for PHP 5.6. + +Available failover modes: + - \\RedisCluster::FAILOVER_NONE - only send commands to master nodes (default) + - \\RedisCluster::FAILOVER_ERROR - failover to slaves for read commands if master is unavailable (recommended) + - \\RedisCluster::FAILOVER_DISTRIBUTE - randomly distribute read commands across master and slaves + +WARNING: FAILOVER_DISTRIBUTE is a not recommended setting and we strongly +suggest to not use it if you use Redis for file locking. Due to the way Redis +is synchronised it could happen, that the read for an existing lock is +scheduled to a slave that is not fully synchronised with the connected master +which then causes a FileLocked exception. + +See https://redis.io/topics/cluster-spec for details about the Redis cluster + :: 'memcached_servers' => array( @@ -1300,7 +1327,7 @@ Using Object Store with Nextcloud 'objectstore' => [ 'class' => 'OC\\Files\\ObjectStore\\Swift', 'arguments' => [ - // trystack will user your facebook id as the user name + // trystack will use your facebook id as the user name 'username' => 'facebook100000123456789', // in the trystack dashboard go to user -> settings -> API Password to // generate a password @@ -1352,11 +1379,25 @@ Global settings for Sharing 'sharing.managerFactory' => '\OC\Share20\ProviderFactory', Replaces the default Share Provider Factory. This can be utilized if -own or 3rdParty Share Providers be used that – for instance – uses the +own or 3rdParty Share Providers are used that – for instance – use the filesystem instead of the database to keep the share information. Defaults to ``\OC\Share20\ProviderFactory`` +:: + + 'sharing.maxAutocompleteResults' => 0, + +Define max number of results returned by the user search for auto-completion +Default is unlimited (value set to 0). + +:: + + 'sharing.minSearchStringLength' => 0, + +Define the minimum length of the search string before we start auto-completion +Default is no limit (value set to 0) + All other configuration options ------------------------------- @@ -1382,16 +1423,23 @@ 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 +During setup, if requirements are met (see below), this setting is set to true +and MySQL can handle 4 byte characters instead of 3 byte characters. + +If you want to convert an existing 3-byte setup into a 4-byte setup please +set the parameters in MySQL as mentioned below and run the migration command: +./occ db:convert-mysql-charset +The config setting will be set automatically after a successful run. + +Consult the documentation for more details. 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 +innodb_large_prefix=ON +innodb_file_format=Barracuda +innodb_file_per_table=ON Tables will be created with * character set: utf8mb4 @@ -1405,8 +1453,6 @@ https://mariadb.com/kb/en/mariadb/xtradbinnodb-server-system-variables/#innodb_l 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( @@ -1616,7 +1662,7 @@ Defaults to ``true`` 'filelocking.ttl' => 60*60, -Set the time-to-live for locks in secconds. +Set the lock's time-to-live in seconds. Any lock older than this will be automatically cleaned up. @@ -1634,6 +1680,18 @@ is highly recommended to *avoid data loss*. Defaults to ``none`` +:: + + 'filelocking.debug' => false, + +Enable locking debug logging + +Note that this can lead to a very large volume of log items being written which can lead +to performance degradation and large log files on busy instance. + +Thus enabling this in production for longer periods of time is not recommended +or should be used together with the ``log.condition`` setting. + :: 'upgrade.disable-web' => false, @@ -1677,6 +1735,25 @@ configuration. DO NOT ADD THIS SWITCH TO YOUR CONFIGURATION! If you, brave person, have read until here be aware that you should not modify *ANY* settings in this file without reading the documentation. +:: + + 'lookup_server' => 'https://lookup.nextcloud.com', + +use a custom lookup server to publish user data + +:: + + 'gs.enabled' => false, + +set to true if the server is used in a setup based on Nextcloud's Global Scale architecture + +:: + + 'gs.federation' => 'internal', + +by default federation is only used internally in a Global Scale setup +If you want to allow federation outside of your environment set it to 'global' + .. ALL_OTHER_SECTIONS_END .. Generated content above. Don't change this. diff --git a/admin_manual/configuration_server/external_sites.rst b/admin_manual/configuration_server/external_sites.rst index d736c1409..67a2f6d97 100644 --- a/admin_manual/configuration_server/external_sites.rst +++ b/admin_manual/configuration_server/external_sites.rst @@ -2,36 +2,47 @@ Linking External Sites ====================== -You can embed external Web sites inside your Nextcloud pages with the External -Sites app, as this screenshot shows. +You can embed external websites or documents inside your Nextcloud pages with the External +sites app, as this screenshot shows. .. figure:: ../images/external-sites-1.png - :scale: 60% + :scale: 70% *Click to enlarge* -This is useful for quick access to important Web pages such as the +This is useful for quick access to important pages such as the Nextcloud manuals and informational pages for your company, and for presenting external pages inside your custom Nextcloud branding, if you use your own custom themes. -The External sites app is included in all versions of Nextcloud. Go to **Apps > -Not Enabled** to enable it. Then go to your Nextcloud Admin page to create your -links, which are saved automatically. There is a dropdown menu to select an -icon, but there is only one default icon so you don't have to select one. Hover -your cursor to the right of your links to make the trashcan icon appear when you +The External sites app is included in all versions of Nextcloud. Go to **Settings > Apps > +Disabled apps** to enable it. Then go to your Nextcloud **Settings > Admin > Additional +settings** to create your links, which are saved automatically. + +Each link can have a unique icon, icons are currently loaded from ``apps/external/img/``. +If you select a language, the link will only be displayed for users with the selected language. +This allows you to have different documentation links for users depending on their language. + +It is also possible to add links for a special device (recognized by the user agent). +Currently the following options are available: All devices, Android app, iOS app, Desktop client and all others (Browsers). + +Hover your cursor over a row to make the trashcan icon appear when you want to remove them. .. figure:: ../images/external-sites-2.png :scale: 80% *Click to enlarge* - -The links appear in the Nextcloud dropdown menu on the top left after -refreshing your page, and have globe icons. + +The links appear in the Nextcloud menu on the top or in the settings menu, after +reloading the page. .. figure:: ../images/external-sites-3.png + +Configurations preventing embedding +----------------------------------- + Your links may or may not work correctly due to the various ways that Web browsers and Web sites handle HTTP and HTTPS URLs, and because the External Sites app embeds external links in IFrames. Modern Web browsers try very hard @@ -56,4 +67,4 @@ On this page, X-Frame-Options prevents the embedding. .. figure:: ../images/external-sites-5.png There isn't much you can do about these issues, but if you're curious you can -see what is happening. \ No newline at end of file +see what is happening. diff --git a/admin_manual/configuration_server/harden_server.rst b/admin_manual/configuration_server/harden_server.rst index e515a4b5a..93367b40f 100644 --- a/admin_manual/configuration_server/harden_server.rst +++ b/admin_manual/configuration_server/harden_server.rst @@ -119,11 +119,22 @@ VirtualHost file:: ServerName cloud.nextcloud.com - Header always set Strict-Transport-Security "max-age=15552000; includeSubDomains; preload" + Header always set Strict-Transport-Security "max-age=15552000; includeSubDomains" - -This example configuration will make all subdomains only accessible via HTTPS. If you have subdomains not accessible via HTTPS, remove ``includeSubdomains;``. + +.. warning:: + We recommend the additional setting ``; preload`` to be added to that header. + Then the domain will be added to an hardcoded list that is shipped with all + major browsers and enforce HTTPS upon those domains. See the `HSTS preload + website for more information `_. Due to the policy + of this list you need to add it to the above example for yourself once you + are sure that this is what you want. `Removing the domain from this list + `_ could take some months until it reaches + all installed browsers. + +This example configuration will make all subdomains only accessible via HTTPS. +If you have subdomains not accessible via HTTPS, remove ``includeSubdomains;``. This requires the ``mod_headers`` extension in Apache. diff --git a/admin_manual/configuration_server/index.rst b/admin_manual/configuration_server/index.rst index 49802776a..885674a05 100644 --- a/admin_manual/configuration_server/index.rst +++ b/admin_manual/configuration_server/index.rst @@ -1,6 +1,6 @@ -============================== -Nextcloud Server Configuration -============================== +==================== +Server Configuration +==================== .. toctree:: :maxdepth: 2 diff --git a/admin_manual/configuration_server/language_configuration.rst b/admin_manual/configuration_server/language_configuration.rst index 177b9d9d7..1cd988c95 100644 --- a/admin_manual/configuration_server/language_configuration.rst +++ b/admin_manual/configuration_server/language_configuration.rst @@ -1,19 +1,16 @@ Language Configuration ====================== +Default language +---------------- + In normal cases Nextcloud will automatically detect the language of the Web-GUI. If this does not work properly or you want to make sure that Nextcloud always -starts with a given language, you can use the **default_language** parameter. +starts with a given language, you can set a **default_language** parameter in the +:file:`config/config.php`. -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 `Transifex language codes -`_ for the list of valid language -codes. - -Parameters ----------- +.. note:: The default_language paramenter is only used, when the browser does not + send any language, and the user hasn't configured own language preferences. :: @@ -21,4 +18,24 @@ Parameters "default_language" => "en", -This parameters can be set in the :file:`config/config.php` + +Force language +-------------- + +If you want to force a specific language, users will no longer be able to change +their language in the personal settings. You can set a **force_language** parameter +in the :file:`config/config.php`. + +:: + + "en", + + +If users shall be unable to change their language, but users have different languages, +this value can be set to ``true`` instead of a language code. + +.. note:: Please check `Transifex language codes + `_ for the list of valid language + codes. diff --git a/admin_manual/configuration_server/logging_configuration.rst b/admin_manual/configuration_server/logging_configuration.rst index f2f3a7067..ec04f9fec 100644 --- a/admin_manual/configuration_server/logging_configuration.rst +++ b/admin_manual/configuration_server/logging_configuration.rst @@ -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 diff --git a/admin_manual/configuration_server/occ_command.rst b/admin_manual/configuration_server/occ_command.rst index 99f026869..8a1ffdd42 100644 --- a/admin_manual/configuration_server/occ_command.rst +++ b/admin_manual/configuration_server/occ_command.rst @@ -44,8 +44,7 @@ occ Command Directory Run occ As Your HTTP User ------------------------- -The HTTP user is different on the various Linux distributions. See -:ref:`strong_perms_label` to learn how to find your HTTP user. +The HTTP user is different on the various Linux distributions: * The HTTP user and group in Debian/Ubuntu is www-data. * The HTTP user and group in Fedora/CentOS is apache. @@ -538,7 +537,7 @@ see a list of modules only if you have enabled the Encryption app. Use ``encryption:set-default-module [module name]`` to set your desired module. ``encryption:encrypt-all`` encrypts all data files for all users. You must first -put your Nextcloud server into :ref:`single-user +put your Nextcloud server into :ref:`maintenance mode` to prevent any user activity until encryption is completed. @@ -548,12 +547,12 @@ user:: sudo -u www-data php occ encryption:decrypt freda Users must have enabled recovery keys on their Personal pages. You must first -put your Nextcloud server into :ref:`single-user +put your Nextcloud server into :ref:`maintenance mode ` to prevent any user activity until decryption is completed. Use ``encryption:disable`` to disable your encryption module. You must first put -your Nextcloud server into :ref:`single-user mode ` +your Nextcloud server into :ref:`maintenance mode ` to prevent any user activity. ``encryption:enable-master-key`` creates a new master key, which is used for all @@ -713,7 +712,7 @@ Verify your app:: sudo -u www-data php occ integrity:check-app --path=/pathto/app appname When it returns nothing, your app is signed correctly. When it returns a message then there is an error. See `Code Signing -`_ in the Developer manual for more detailed information. +`_ in the Developer manual for more detailed information. .. TODO ON RELEASE: Update version number above on release ``integrity:sign-core`` is for Nextcloud core developers only. @@ -864,12 +863,12 @@ Use these commands when you upgrade Nextcloud, manage encryption, perform backups and other tasks that require locking users out until you are finished:: maintenance - maintenance:mimetype:update-db Update database mimetypes and update - filecache - maintenance:mimetype:update-js Update mimetypelist.js - maintenance:mode set maintenance mode - maintenance:repair repair this installation - maintenance:singleuser set single user mode + maintenance:data-fingerprint update the systems data-fingerprint after a backup is restored + maintenance:mimetype:update-db Update database mimetypes and update filecache + maintenance:mimetype:update-js Update mimetypelist.js + maintenance:mode set maintenance mode + maintenance:repair repair this installation + maintenance:update:htaccess Updates the .htaccess file ``maintenance:mode`` locks the sessions of all logged-in users, including administrators, and displays a status screen warning that the server is in @@ -879,18 +878,10 @@ logged-in users must refresh their Web browsers to continue working:: sudo -u www-data php occ maintenance:mode --on sudo -u www-data php occ maintenance:mode --off - -Putting your Nextcloud server into single-user mode allows admins to log in and -work, but not ordinary users. This is useful for performing maintenance and -troubleshooting on a running server:: - sudo -u www-data php occ maintenance:singleuser --on - Single user mode enabled - -Turn it off when you're finished:: - - sudo -u www-data php occ maintenance:singleuser --off - Single user mode disabled +After restoring a backup of your data directory or the database, you should always +call ``maintenance:data-fingerprint`` once. This changes the ETag for all files +in the communication with sync clients, allowing them to realize a file was modified. The ``maintenance:repair`` command runs automatically during upgrades to clean up the database, so while you can run it manually there usually isn't a need @@ -1132,9 +1123,7 @@ You can install Nextcloud entirely from the command line. After downloading the tarball and copying Nextcloud into the appropriate directories you can use ``occ`` commands in place of running the graphical Installation Wizard. -Apply correct permissions to your Nextcloud directories; see -:ref:`strong_perms_label`. Then choose your ``occ`` options. This lists your -available options:: +Then choose your ``occ`` options. This lists your available options:: sudo -u www-data php /var/www/nextcloud/occ Nextcloud is not installed - only a limited number of commands are available diff --git a/admin_manual/configuration_server/security_setup_warnings.rst b/admin_manual/configuration_server/security_setup_warnings.rst index 51873b9af..e74f077f6 100644 --- a/admin_manual/configuration_server/security_setup_warnings.rst +++ b/admin_manual/configuration_server/security_setup_warnings.rst @@ -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 `_ 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 `_ +and might again in the future. Please, protect your privacy and keep your server +up to date! Privacy means little without security. + Cache Warnings -------------- @@ -53,7 +59,7 @@ describe how to enable HTTPS on the Apache and Nginx Web servers. :ref:`use_https_label` -:doc:`../installation/nginx_examples` +:doc:`../installation/nginx` The test with getenv(\"PATH\") only returns an empty response ------------------------------------------------------------- diff --git a/admin_manual/configuration_server/server_tuning.rst b/admin_manual/configuration_server/server_tuning.rst index ce16b9572..3dd26eed2 100644 --- a/admin_manual/configuration_server/server_tuning.rst +++ b/admin_manual/configuration_server/server_tuning.rst @@ -1,6 +1,6 @@ -======================= -Nextcloud Server Tuning -======================= +============= +Server Tuning +============= Using cron to perform background jobs ------------------------------------- @@ -73,8 +73,6 @@ Enable HTTP2 for faster loading HTTP2 has `huge speed improvements `_ over HTTP with multiple request. Most `browsers already support HTTP2 over SSL (HTTPS) `_. So refer to your server manual for guides on how to use HTTP2. -.. _opcache: - Enable PHP OPcache ------------------ @@ -82,7 +80,7 @@ The `OPcache `_ improves the perform .. code:: ini - opcache.enable=On + opcache.enable=1 opcache.enable_cli=1 opcache.interned_strings_buffer=8 opcache.max_accelerated_files=10000 diff --git a/admin_manual/configuration_server/theming.rst b/admin_manual/configuration_server/theming.rst index 1b1a98956..256babcfc 100644 --- a/admin_manual/configuration_server/theming.rst +++ b/admin_manual/configuration_server/theming.rst @@ -2,7 +2,21 @@ Theming ======= -In the administrative settings you can modify the appearance of Nextcloud: +Nextcloud has two ways of theming. There is a theming app that provides a web +UI to set up theming. The second option allows to overwrite most of the files +but a customized theme needs to be created and maintained. For more information on +this check out the `developers documentation <../../developer_manual/core/theming.html>`_. + +We recommend to use the theming app, because the Nextcloud team maintains this +and verifies that all adjustments to the server work with the theming. It +covers also most use cases like replacing the name, logos and colors. + +Theming app +=========== + +Check in the apps management that the theming app is enabled. Then the +administrator settings show a section where you can modify the appearance of +your Nextcloud: * Name * Web Address @@ -30,3 +44,18 @@ This requires the following additional dependencies: - PHP module imagick - SVG support for imagick (e.g. `libmagickcore5-extra`) +Theming of mobile app URLs and IDs +================================== + +The themes supported to change the URLs to the mobile apps (Android & iOS) that +is shown when the web UI is opened on one of those devices. Then there was a +header shown, that redirects the user to the app in the app store. By default +this redirects to the Nextcloud apps. In some cases it is wanted that this +links to branded versions of those apps. In those cases the IDs and URLs can be +set via the occ command:: + + occ config:app:set theming AndroidClientUrl --value "https://play.google.com/store/apps/details?id=com.nextcloud.client" + occ config:app:set theming iTunesAppId --value "1125420102" + occ config:app:set theming iOSClientUrl --value "https://itunes.apple.com/us/app/nextcloud/id1125420102?mt=8" + +This feature was added in version 12.0.1 and 13. diff --git a/admin_manual/configuration_user/index.rst b/admin_manual/configuration_user/index.rst index 18ac09090..f3d3a9170 100644 --- a/admin_manual/configuration_user/index.rst +++ b/admin_manual/configuration_user/index.rst @@ -13,4 +13,5 @@ User Management user_auth_ftp_smb_imap user_auth_ldap user_auth_ldap_cleanup + user_auth_ldap_api user_provisioning_api diff --git a/admin_manual/configuration_user/two_factor-auth.rst b/admin_manual/configuration_user/two_factor-auth.rst index 3f1315519..fb13e1c04 100644 --- a/admin_manual/configuration_user/two_factor-auth.rst +++ b/admin_manual/configuration_user/two_factor-auth.rst @@ -7,7 +7,7 @@ Starting with Nextcloud 10, it is possible to use two factor authentication Several 2FA apps are already available including `TOTP `_, SMS 2-factor and `U2F `_. -Developers can `built new two-factor provider apps `_. +Developers can `built new two-factor provider apps `_. .. TODO ON RELEASE: Update version number above on release Enabling Two Factor Authentication @@ -19,5 +19,5 @@ 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. `_ +Once 2FA has been enabled, users have to `activate it in their personal settings. `_ .. TODO ON RELEASE: Update version number above on release diff --git a/admin_manual/configuration_user/user_auth_ldap.rst b/admin_manual/configuration_user/user_auth_ldap.rst index b45f26bcf..5f77bc224 100644 --- a/admin_manual/configuration_user/user_auth_ldap.rst +++ b/admin_manual/configuration_user/user_auth_ldap.rst @@ -389,9 +389,24 @@ Enable LDAP password changes per user: * Additional requirements for Active Directory: - * At least a 128-bit transport encryption must be used for the communication between Nextcloud and the LDAP server + * 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: + This feature requires OpenLDAP with ppolicy. The DN of a default password policy will be used for password expiry handling in the absence of any user specific password policy. Password expiry handling features the following: + + * When a LDAP password is about to expire, display a warning message to the user showing the number of days left before it expires. Password expiry warnings are displayed through the notifications app for Nextcloud. + + * Prompt LDAP users with expired passwords to reset their password during login, provided that an adequate number of grace logins is still available. + + Leave the setting empty to keep password expiry handling disabled. + + For the password expiry handling feature to work, LDAP password changes per user must be enabled and the LDAP server must be running OpenLDAP with its ppolicy module configured accordingly. + + * Example: + + | *cn=default,ou=policies,dc=my-company,dc=com* + Special Attributes ^^^^^^^^^^^^^^^^^^ diff --git a/admin_manual/configuration_user/user_auth_ldap_api.rst b/admin_manual/configuration_user/user_auth_ldap_api.rst new file mode 100644 index 000000000..0151e84b2 --- /dev/null +++ b/admin_manual/configuration_user/user_auth_ldap_api.rst @@ -0,0 +1,306 @@ +====================== +LDAP Configuration API +====================== + +Any used method requires the a header "OCS-APIREQUEST" set to "true". And any method takes an optional "format" parameter, which accepts "xml" (default) or "json". + +Methods +======= + +Creating a configuration +------------------------ + +Creates a new and empty LDAP configuration. It returns its ID. Authentication is done by sending a +basic HTTP authentication header. + +**Syntax: ocs/v2.php/apps/user_ldap/api/v1/config** + +* HTTP method: POST + +Example +^^^^^^^ + +* POST ``https://admin:secret@example.com/ocs/v2.php/apps/user_ldap/api/v1/config`` -H "OCS-APIREQUEST: true" +* Creates a new, empty configuration + +XML Output +^^^^^^^^^^ + +.. code-block:: xml + + + + + ok + 200 + OK + + + s01 + + + + +Deleting a configuration +------------------------ + +Deletes a given LDAP configuration. Authentication is done by sending a basic HTTP authentication header. + +**Syntax: ocs/v2.php/apps/user_ldap/api/v1/config/{configID}** + +* HTTP method: DELETE + +Example +^^^^^^^ + +* DELETE ``https://admin:secret@example.com/ocs/v2.php/apps/user_ldap/api/v1/config/s02 -H "OCS-APIREQUEST: true"`` +* deletes the LDAP configuration + +XML Output +^^^^^^^^^^ + +.. code-block:: xml + + + + + ok + 200 + OK + + + + + +Reading a configuration +----------------------- + +Returns all keys and values of the specified LDAP configuration. Authentication is done by sending a basic HTTP authentication header. + +**Syntax: ocs/v2.php/apps/user_ldap/api/v1/config/{configID}** + +* HTTP method: GET +* url argument: showPassword - int, optional, default 0, whether to return the password in clear text + +Example +^^^^^^^ + +* GET ``https://admin:secret@example.com/ocs/v2.php/apps/user_ldap/api/v1/config/s02?showPassword=1 -H "OCS-APIREQUEST: true"`` +* fetches the LDAP configuration + +XML Output +^^^^^^^^^^ + +.. code-block:: xml + + + + + ok + 200 + OK + + + ldap://ldap.server.tld + 389 + + + ou=Department XLII,dc=example,dc=com + ou=users,ou=Department XLII,dc=example,dc=com + ou=Department XLII,dc=example,dc=com + cn=root,dc=example,dc=com + Secret + 1 + 0 + + displayname + uid + gidNumber + inetOrgPerson + + (&(objectclass=nextcloudUser)(nextcloudEnabled=TRUE)) + 1 + (&(|(objectclass=nextcloudGroup))) + 0 + nextcloudGroup + + memberUid + cn + (&(|(objectclass=inetOrgPerson))(uid=%uid)) + 0 + 0 + 1 + + + 20 MB + mail + 600 + auto + auto + + 1 + uid;sn;givenname + + 0 + attr:mail + + 1 + 1 + + + + 0 + 0 + 500 + 1 + + + + + +Modifying a configuration +------------------------- + +Updates a configuration with the provided values. Authentication is done by sending a basic HTTP authentication header. + +**Syntax: ocs/v2.php/apps/user_ldap/api/v1/config/{configID}** + +* HTTP method: PUT +* url argument: configData - array, see table below for the fields. All fields are optional. The values must be url-encoded. + +Example +^^^^^^^ + +* PUT ``https://admin:secret@example.com/ocs/v2.php/apps/user_ldap/api/v1/config/s01 -H "OCS-APIREQUEST: true" -d "configData[ldapHost]=ldap%3A%2F%2Fldap.server.tld &configData[ldapPort]=389"`` +* fetches the LDAP configuration + +XML Output +^^^^^^^^^^ + +.. code-block:: xml + + + + + ok + 200 + OK + + + + +Configuration Keys +================== + ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| Key | Mode | Required | Description | ++===============================+======+==========+=======================================================================================================================+ +| ldapHost | rw | yes | LDAP server host, supports protocol | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapPort | rw | yes | LDAP server port | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapBackupHost | rw | no | LDAP replica host | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapBackupPort | rw | no | LDAP replica port | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapOverrideMainServer | rw | no | Whether replica should be used instead | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapBase | rw | yes | Base | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapBaseUsers | rw | no | Base for users, defaults to general base if not specified | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapBaseGroups | rw | no | Base for groups, defaults to general base if not specified | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapAgentName | rw | no | DN for the (service) user to connect to LDAP | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapAgentPassword | rw | no | Password for the service user | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapTLS | rw | no | Whether to use StartTLS | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| turnOffCertCheck | rw | no | Turns off certificate validation for TLS connections | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapIgnoreNamingRules | rw | no | Backwards compatibility, do not set it. | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapUserDisplayName | rw | yes | Attribute used as display name for users | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapUserDisplayName2 | rw | no | Additional attribute, if set show on brackets next to the main attribute | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapGidNumber | rw | no | group ID attribute, needed for primary groups on OpenLDAP (and compatible) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapUserFilterObjectclass | rw | no | set by the Settings Wizard (web UI) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapUserFilterGroups | rw | no | set by the Settings Wizard (web UI) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapUserFilter | rw | yes | LDAP Filter used to retrieve user | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapUserFilterMode | rw | no | used by the Settings Wizard, set to 1 for manual editing | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapAttributesForUserSearch | rw | no | attributes to be matched when searching for users. separate by ; | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapGroupFilter | rw | no | LDAP Filter used to retrieve groups | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapGroupFilterMode | rw | no | used by the Settings Wizard, set to 1 for manual editing | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapGroupFilterObjectclass | rw | no | set by the Settings Wizard (web UI) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapGroupFilterGroups | rw | no | set by the Settings Wizard (web UI) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapGroupMemberAssocAttr | rw | no | attribute that indicates group members, one of: member, memberUid, uniqueMember, gidNumber | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapGroupDisplayName | rw | no | Attribute used as display name for groups, required if groups are used | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapAttributesForGroupSearch | rw | no | attributes to be matched when searching for groups. separate by ; | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapLoginFilter | rw | yes | LDAP Filter used to authenticate users | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapLoginFilterMode | rw | no | used by the Settings Wizard, set to 1 for manual editing | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapLoginFilterEmail | rw | no | set by the Settings Wizard (web UI) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapLoginFilterUsername | rw | no | set by the Settings Wizard (web UI) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapLoginFilterAttributes | rw | no | set by the Settings Wizard (web UI) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapQuotaAttribute | rw | no | LDAP attribute containing the quote value (per user) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapQuotaDefault | rw | no | Default Quota, if specified quota attribute is empty | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapEmailAttribute | rw | no | LDAP attribute containing the email address (takes first if multiple are stored) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapCacheTTL | rw | no | How long results from LDAP are cached, defaults to 10min | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapUuidUserAttribute | r | no | set in runtime | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapUuidGroupAttribute | r | no | set in runtime | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapConfigurationActive | rw | no | whether this configuration is active. 1 is on, 0 is off. | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapExperiencedAdmin | rw | no | used by the Settings Wizard, set to 1 for manual editing | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| homeFolderNamingRule | rw | no | LDAP attribute to use a user folder name | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| hasPagedResultSupport | r | no | set in runtime | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| hasMemberOfFilterSupport | r | no | set in runtime | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| useMemberOfToDetectMembership | rw | no | Whether to use memberOf to detect group memberships | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapExpertUsernameAttr | rw | no | LDAP attribute to use as internal username. Might be modified (e.g. to avoid name collisions, character restrictions) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapExpertUUIDUserAttr | rw | no | override the LDAP servers UUID attribute to identify LDAP user records | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapExpertUUIDGroupAttr | rw | no | override the LDAP servers UUID attribute to identify LDAP group records | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| lastJpegPhotoLookup | r | no | set in runtime | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapNestedGroups | rw | no | Whether LDAP supports nested groups | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapPagingSize | rw | no | Number of results to return per page | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| turnOnPasswordChange | rw | no | Whether users are allowed to change passwords (hashing must happen on LDAP!) | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapDynamicGroupMemberURL | rw | no | URL for dynamic groups | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ +| ldapDefaultPPolicyDN | rw | no | PPolicy DN for password rules | ++-------------------------------+------+----------+-----------------------------------------------------------------------------------------------------------------------+ + diff --git a/admin_manual/configuration_user/user_configuration.rst b/admin_manual/configuration_user/user_configuration.rst index c6caabe27..e9816b5c5 100644 --- a/admin_manual/configuration_user/user_configuration.rst +++ b/admin_manual/configuration_user/user_configuration.rst @@ -13,19 +13,20 @@ On the User management page of your Nextcloud Web UI you can: * View and set quotas * Create and edit their email addresses * Send an automatic email notification to new users +* Disable and Enable users * Delete them with a single click The default view displays basic information about your users. .. figure:: ../images/users-config.png -The Group filters on the left sidebar lets you quickly filter users by their +The Group filters on the left sidebar lets you quickly filter users by their group memberships, and create new groups. .. figure:: ../images/users-config-1.png -Click the gear icon on the lower left sidebar to set a default storage quota, -and to display additional fields: **Show storage location, Show last log in, +Click the gear icon on the lower left sidebar to set a default storage quota, +and to display additional fields: **Show storage location, Show last log in, Show user backend, Send email to new users,** and **Show email address**. .. figure:: ../images/users-config-2.png @@ -36,25 +37,25 @@ User accounts have the following properties: The unique ID of an Nextcloud user, and it cannot be changed. *Full Name* - The user's display name that appears on file shares, the Nextcloud Web - interface, and emails. Admins and users may change the Full Name anytime. If + The user's display name that appears on file shares, the Nextcloud Web + interface, and emails. Admins and users may change the Full Name anytime. If the Full Name is not set it defaults to the login name. *Password* - The admin sets the new user's first password. Both the user and the admin can + The admin sets the new user's first password. Both the user and the admin can change the user's password at anytime. *Groups* - You may create groups, and assign group memberships to users. By default new + You may create groups, and assign group memberships to users. By default new users are not assigned to any groups. *Group Admin* - Group admins are granted administrative privileges on specific groups, and + Group admins are granted administrative privileges on specific groups, and can add and remove users from their groups. *Quota* - The maximum disk space assigned to each user. Any user that exceeds the quota - cannot upload or sync data. You have the the option to include external + The maximum disk space assigned to each user. Any user that exceeds the quota + cannot upload or sync data. You have the the option to include external storage in user quotas. Creating a New User @@ -62,128 +63,152 @@ Creating a New User To create a user account: -* Enter the new user's **Login Name** and their initial **Password** +* Enter the new user's **Login Name** and their initial **Password** * Optionally, assign **Groups** memberships * Click the **Create** button .. figure:: ../images/users-create.png -Login names may contain letters (a-z, A-Z), numbers (0-9), dashes (-), -underscores (_), periods (.) and at signs (@). After creating the user, you -may fill in their **Full Name** if it is different than the login name, or +Login names may contain letters (a-z, A-Z), numbers (0-9), dashes (-), +underscores (_), periods (.) and at signs (@). After creating the user, you +may fill in their **Full Name** if it is different than the login name, or leave it for the user to complete. -If you have checked **Send email to new user** in the control panel on the -lower left sidebar, you may also enter the new user's email address, and -Nextcloud will automatically send them a notification with their new login -information. You may edit this email using the email template editor on your +If you have checked **Send email to new user** in the control panel on the +lower left sidebar, you may also enter the new user's email address, and +Nextcloud will automatically send them a notification with their new login +information. You may edit this email using the email template editor on your Admin page (see :doc:`../configuration_server/email_configuration`). +Set the **Send email to new user**-checkbox allows you to leave the **Password** +field empty. The user will get an activation-email to set his own password. + Reset a User's Password ~~~~~~~~~~~~~~~~~~~~~~~ You cannot recover a user's password, but you can set a new one: * Hover your cursor over the user's **Password** field -* Click on the **pencil icon** -* Enter the user's new password in the password field, and remember to provide +* Click on the **pencil icon** +* Enter the user's new password in the password field, and remember to provide the user with their password - -If you have encryption enabled, there are special considerations for user -password resets. Please see + +If you have encryption enabled, there are special considerations for user +password resets. Please see :doc:`../configuration_files/encryption_configuration`. Renaming a User ~~~~~~~~~~~~~~~ -Each Nextcloud user has two names: a unique **Login Name** used for -authentication, and a **Full Name**, which is their display name. You can edit +Each Nextcloud user has two names: a unique **Login Name** used for +authentication, and a **Full Name**, which is their display name. You can edit the display name of a user, but you cannot change the login name of any user. To set or change a user's display name: * Hover your cursor over the user's **Full Name** field -* Click on the **Pencil icon** +* Click on the **Pencil icon** * Enter the user's new display name Granting Administrator Privileges to a User ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Nextcloud has two types of administrators: **Super Administrators** and **Group -Administrators**. Group administrators have the rights to create, edit and -delete users in their assigned groups. Group administrators cannot access -system settings, or add or modify users in the groups that they are not **Group -Administrators** for. Use the dropdown menus in the **Group Admin** column to +Nextcloud has two types of administrators: **Super Administrators** and **Group +Administrators**. Group administrators have the rights to create, edit and +delete users in their assigned groups. Group administrators cannot access +system settings, or add or modify users in the groups that they are not **Group +Administrators** for. Use the dropdown menus in the **Group Admin** column to assign group admin privileges. .. figure:: ../images/users-groups.png -**Super Administrators** have full rights on your Nextcloud server, and can -access and modify all settings. To assign the **Super Administrators** role to +**Super Administrators** have full rights on your Nextcloud server, and can +access and modify all settings. To assign the **Super Administrators** role to a user, simply add them to the ``admin`` group. Managing Groups ~~~~~~~~~~~~~~~ -You can assign new users to groups when you create them, and create new groups -when you create new users. You may also use the **Add Group** button at the top -of the left pane to create new groups. New group members will immediately +You can assign new users to groups when you create them, and create new groups +when you create new users. You may also use the **Add Group** button at the top +of the left pane to create new groups. New group members will immediately have access to file shares that belong to their new groups. Setting Storage Quotas ~~~~~~~~~~~~~~~~~~~~~~ -Click the gear on the lower left pane to set a default storage quota. This is -automatically applied to new users. You may assign a different quota to any user -by selecting from the **Quota** dropdown, selecting either a preset value or -entering a custom value. When you create custom quotas, use the normal +Click the gear on the lower left pane to set a default storage quota. This is +automatically applied to new users. You may assign a different quota to any user +by selecting from the **Quota** dropdown, selecting either a preset value or +entering a custom value. When you create custom quotas, use the normal abbreviations for your storage values such as 500 MB, 5 GB, 5 TB, and so on. -You now have a configurable option in ``config.php`` that controls whether -external storage is counted against user's quotas. This is still -experimental, and may not work as expected. The default is to not count -external storage as part of user storage quotas. If you prefer to include it, +You now have a configurable option in ``config.php`` that controls whether +external storage is counted against user's quotas. This is still +experimental, and may not work as expected. The default is to not count +external storage as part of user storage quotas. If you prefer to include it, then change the default ``false`` to ``true``.:: 'quota_include_external_storage' => false, -Metadata (such as thumbnails, temporary files, and encryption keys) takes up -about 10% of disk space, but is not counted against user quotas. Users can check -their used and available space on their Personal pages. Only files that -originate with users count against their quotas, and not files shared with them -that originate from other users. For example, if you upload files to a -different user's share, those files count against your quota. If you re-share a -file that another user shared with you, that file does not count against your +Metadata (such as thumbnails, temporary files, and encryption keys) takes up +about 10% of disk space, but is not counted against user quotas. Users can check +their used and available space on their Personal pages. Only files that +originate with users count against their quotas, and not files shared with them +that originate from other users. For example, if you upload files to a +different user's share, those files count against your quota. If you re-share a +file that another user shared with you, that file does not count against your quota, but the originating user's. -Encrypted files are a little larger than unencrypted files; the unencrypted size +Encrypted files are a little larger than unencrypted files; the unencrypted size is calculated against the user's quota. -Deleted files that are still in the trash bin do not count against quotas. The -trash bin is set at 50% of quota. Deleted file aging is set at 30 days. When -deleted files exceed 50% of quota then the oldest files are removed until the +Deleted files that are still in the trash bin do not count against quotas. The +trash bin is set at 50% of quota. Deleted file aging is set at 30 days. When +deleted files exceed 50% of quota then the oldest files are removed until the total is below 50%. -When version control is enabled, the older file versions are not counted +When version control is enabled, the older file versions are not counted against quotas. -When a user creates a public share via URL, and allows uploads, any uploaded +When a user creates a public share via URL, and allows uploads, any uploaded files count against that user's quota. +Disable and Enable users +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. figure:: ../images/users-actions.png + +Sometimes you may want to disable a user without permanently deleting his +settings and files. The user can be activated any time again, without data-loss. + +Hover your cursor over their name on the **Users** page until the "..."-menu icon +appears at the far right. After clicking on it, you will see the **Disable** option. + +The user will not longer be able to access his Nextcloud until you enable him again. +Keep in mind that the files, which were shared by this user will not longer be accessible. + +You will find all disabled users in the **disabled**-section on the left pane. +Enabling users is as easy as disabling them. Just click on the "..."-menu, and +select **Enable**. + Deleting users ~~~~~~~~~~~~~~ -Deleting a user is easy: hover your cursor over their name on the **Users** page -until a trashcan icon appears at the far right. Click the trashcan, and they're -gone. You'll see an undo button at the top of the page, which remains until you -refresh the page. When the undo button is gone you cannot recover the deleted -user. +.. figure:: ../images/users-actions.png -All of the files owned by the user are deleted as well, including all files they +Deleting a user is easy: hover your cursor over their name on the **Users** page +until the "..."-menu icon appears at the far right. After clicking on it, you will +see the **Delete** option. Clicking on it, delets a user with all his data immediately. + +You'll see an undo button at the top of the page, which remains for some seconds. +When the undo button is gone you cannot recover the deleted user. + +All of the files owned by the user are deleted as well, including all files they have shared. If you need to preserve the user's files and shares, you must first -download them from your Nextcloud Files page, which compresses them into a zip -file, or use a sync client to copy them to your local computer. See -:doc:`../configuration_files/file_sharing_configuration` to learn how to create +download them from your Nextcloud Files page, which compresses them into a zip +file, or use a sync client to copy them to your local computer. See +:doc:`../configuration_files/file_sharing_configuration` to learn how to create persistent file shares that survive user deletions. diff --git a/admin_manual/configuration_user/user_provisioning_api.rst b/admin_manual/configuration_user/user_provisioning_api.rst index 91b26eed4..0fc15fd7f 100644 --- a/admin_manual/configuration_user/user_provisioning_api.rst +++ b/admin_manual/configuration_user/user_provisioning_api.rst @@ -20,8 +20,8 @@ All POST requests require the ``Content-Type: application/x-www-form-urlencoded` 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. @@ -49,7 +49,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -61,8 +61,8 @@ XML Output -**users / getusers** --------------------- +Search/get users +---------------- Retrieves a list of users from the Nextcloud server. Authentication is done by sending a Basic HTTP Authorization header. @@ -87,7 +87,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -102,8 +102,8 @@ XML Output -**users / getuser** -------------------- +Get data of a single user +------------------------- Retrieves information about a single user. Authentication is done by sending a Basic HTTP Authorization header. @@ -125,7 +125,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -134,14 +134,24 @@ XML Output ok - frank@example.org - 0 true + Frank + 0 + frank@example.org + Frank K. + 0123 / 456 789 +
Foobar 12, 12345 Town
+ https://nextcloud.com + Nextcloud + + group1 + group2 + -**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 @@ -150,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: @@ -173,7 +194,7 @@ Examples XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -184,8 +205,8 @@ XML Output -**users / disableuser** ------------------------ +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. @@ -208,7 +229,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -220,8 +241,8 @@ XML Output -**users / enableuser** ----------------------- +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. @@ -244,7 +265,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -256,8 +277,8 @@ XML Output -**users / deleteuser** ----------------------- +Delete a user +------------- Deletes a user from the Nextcloud server. Authentication is done by sending a Basic HTTP Authorization header. @@ -280,7 +301,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -291,8 +312,8 @@ XML Output -**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. @@ -314,7 +335,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -330,8 +351,8 @@ XML Output -**users / addtogroup** ----------------------- +Add user to group +----------------- Adds the specified user to the specified group. Authentication is done by sending a Basic HTTP Authorization header. @@ -360,7 +381,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -371,8 +392,8 @@ XML Output -**users / removefromgroup** ---------------------------- +Remove user from group +---------------------- Removes the specified user from the specified group. Authentication is done by sending a Basic HTTP Authorization header. @@ -402,7 +423,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -413,8 +434,8 @@ XML Output -**users / createsubadmin** --------------------------- +Promote user to subadmin +------------------------ Makes a user the subadmin of a group. Authentication is done by sending a Basic HTTP Authorization header. @@ -443,7 +464,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -454,8 +475,8 @@ XML Output -**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. @@ -484,7 +505,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -495,8 +516,8 @@ XML Output -**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. @@ -521,7 +542,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -534,12 +555,49 @@ XML Output testgroup - + +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 + + + + + ok + 100 + + + + + 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. @@ -564,7 +622,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -579,8 +637,8 @@ XML Output -**groups / addgroup** ---------------------- +Create a group +-------------- Adds a new group. Authentication is done by sending a Basic HTTP Authorization header. @@ -607,7 +665,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -618,8 +676,8 @@ XML Output -**groups / getgroup** ---------------------- +Get members of a group +---------------------- Retrieves a list of group members. Authentication is done by sending a Basic HTTP Authorization header. @@ -641,7 +699,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -656,8 +714,8 @@ XML Output -**groups / getsubadmins** -------------------------- +Get subadmins of a group +------------------------ Returns subadmins of the group. Authentication is done by sending a Basic HTTP Authorization header. @@ -682,7 +740,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -696,8 +754,8 @@ XML Output -**groups / deletegroup** ------------------------- +Delete a group +-------------- Removes a group. Authentication is done by sending a Basic HTTP Authorization header. @@ -721,7 +779,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -731,12 +789,12 @@ XML Output - -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 @@ -761,7 +819,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -777,8 +835,8 @@ XML Output -**apps / getappinfo** ---------------------- +Get app info +------------ Provides information on a specific application. Authentication is done by sending a Basic HTTP Authorization header. @@ -800,7 +858,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -831,8 +889,8 @@ XML Output -**apps / enable** ------------------ +Enable an app +------------- Enable an app. Authentication is done by sending a Basic HTTP Authorization header. @@ -854,7 +912,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml @@ -864,8 +922,8 @@ XML Output -**apps / disable** ------------------- +Disable an app +-------------- Disables the specified app. Authentication is done by sending a Basic HTTP Authorization header. @@ -888,7 +946,7 @@ Example XML Output ^^^^^^^^^^ -:: +.. code-block:: xml diff --git a/admin_manual/contents.rst b/admin_manual/contents.rst index ce77bdcaf..dfb59ea45 100644 --- a/admin_manual/contents.rst +++ b/admin_manual/contents.rst @@ -10,7 +10,8 @@ Table of Contents installation/index configuration_server/index configuration_user/index - configuration_files/index + configuration_files/index + file_workflows/index configuration_database/index configuration_mimetypes/index maintenance/index diff --git a/admin_manual/configuration_files/files_access_control.rst b/admin_manual/file_workflows/access_control.rst similarity index 95% rename from admin_manual/configuration_files/files_access_control.rst rename to admin_manual/file_workflows/access_control.rst index 455a05664..0a187b407 100644 --- a/admin_manual/configuration_files/files_access_control.rst +++ b/admin_manual/file_workflows/access_control.rst @@ -98,6 +98,11 @@ option. * **File collaborative tag:** Either the file itself, or any of the file owner's parent folders needs to be tagged with the tag. + + .. note:: Tags used in access control rules should be restricted tags, + otherwise any user can remove the tag to access the file again. + The best way to do this is with the :doc:`automated_tagging`. + * **File mimetype:** The mimetype of the file, e.g. ``text/plain`` * **File size:** The size of the file (*Only available on upload*) diff --git a/admin_manual/file_workflows/automated_tagging.rst b/admin_manual/file_workflows/automated_tagging.rst new file mode 100644 index 000000000..1a3061519 --- /dev/null +++ b/admin_manual/file_workflows/automated_tagging.rst @@ -0,0 +1,31 @@ +========================== +Automated Tagging of Files +========================== + +Nextcloud's Files Automated Tagging app allows to assign collaborative tags +to files and folders based on rules, similar to :doc:`access_control`. + +Assigning restricted and invisible tags +--------------------------------------- + +The main functionality of this app is to allow users to indirectly assign +restricted and invisible tags to files they upload. + +This is especially useful for retention and :doc:`access_control`, so people +that got the files shared can not remove the tag to stop the retention or +allow access against the owners will. + + + .. figure:: images/automated_tagging_sample_rule.png + :alt: Sample rule to assign a restricted tag. + +In the sample you can see a simple rule with only one condition. +It will tag all files with the restricted tag ``Protected file`` that are +uploaded into a folder that is tagged with ``Protect content``. No user can +remove the tag ``Protected file`` and therefor access control and retention +both work fine without users being able to work around them. + +Available rules +--------------- + +The available rules can be seen in the access control section: :ref:`available-rules-label`. diff --git a/admin_manual/file_workflows/images/automated_tagging_sample_rule.png b/admin_manual/file_workflows/images/automated_tagging_sample_rule.png new file mode 100644 index 000000000..ca456eac4 Binary files /dev/null and b/admin_manual/file_workflows/images/automated_tagging_sample_rule.png differ diff --git a/admin_manual/configuration_files/images/files_access_control_block_mimetype.png b/admin_manual/file_workflows/images/files_access_control_block_mimetype.png similarity index 100% rename from admin_manual/configuration_files/images/files_access_control_block_mimetype.png rename to admin_manual/file_workflows/images/files_access_control_block_mimetype.png diff --git a/admin_manual/configuration_files/images/files_access_control_collaborative_tags.png b/admin_manual/file_workflows/images/files_access_control_collaborative_tags.png similarity index 100% rename from admin_manual/configuration_files/images/files_access_control_collaborative_tags.png rename to admin_manual/file_workflows/images/files_access_control_collaborative_tags.png diff --git a/admin_manual/configuration_files/images/files_access_control_sample_rules.png b/admin_manual/file_workflows/images/files_access_control_sample_rules.png similarity index 100% rename from admin_manual/configuration_files/images/files_access_control_sample_rules.png rename to admin_manual/file_workflows/images/files_access_control_sample_rules.png diff --git a/admin_manual/file_workflows/images/retention_sample.png b/admin_manual/file_workflows/images/retention_sample.png new file mode 100644 index 000000000..86087cdd1 Binary files /dev/null and b/admin_manual/file_workflows/images/retention_sample.png differ diff --git a/admin_manual/file_workflows/index.rst b/admin_manual/file_workflows/index.rst new file mode 100644 index 000000000..47804f367 --- /dev/null +++ b/admin_manual/file_workflows/index.rst @@ -0,0 +1,11 @@ +============== +File Workflows +============== + + +.. toctree:: + :maxdepth: 2 + + access_control + automated_tagging + retention diff --git a/admin_manual/file_workflows/retention.rst b/admin_manual/file_workflows/retention.rst new file mode 100644 index 000000000..9bc1fbe8a --- /dev/null +++ b/admin_manual/file_workflows/retention.rst @@ -0,0 +1,33 @@ +================== +Retention of Files +================== + +Nextcloud's Files Retention app allows to automatically delete files that +are tagged with a collaborative tag and have a certain age. + +Sample +------ + + .. figure:: images/retention_sample.png + :alt: Sample rule to delete files after 14 days. + +The rule from the sample will delete all files tagged with ``Temporary file`` after 14 days. + +Common misconfigurations +------------------------ + +Public collaborative tag +======================== + +Similar to :doc:`access_control` retention should use ``restricted`` or ``invisible`` +tags. Otherwise any user can remove the tag and the file is not removed after the given +period. Use :doc:`automated_tagging` to assign such tags to newly uploaded files. + +File age +======== + +Currently retention is based on the creation date of the file. The sync client sends +the **original** creation date to the server, while uploading through the web interface +will create a new file with a **new** creation date. +We hope to be able to add a ``upload date`` to the filesystem soon, which would make more +sense. Until then this potentially unexpected behaviour has to be taken into account. diff --git a/admin_manual/images/external-sites-1.png b/admin_manual/images/external-sites-1.png index efd98fe07..5b6307893 100644 Binary files a/admin_manual/images/external-sites-1.png and b/admin_manual/images/external-sites-1.png differ diff --git a/admin_manual/images/external-sites-2.png b/admin_manual/images/external-sites-2.png index 4924def60..3b359b6d5 100644 Binary files a/admin_manual/images/external-sites-2.png and b/admin_manual/images/external-sites-2.png differ diff --git a/admin_manual/images/external-sites-3.png b/admin_manual/images/external-sites-3.png index 545c93e77..500f9d0c1 100644 Binary files a/admin_manual/images/external-sites-3.png and b/admin_manual/images/external-sites-3.png differ diff --git a/admin_manual/images/ldap-advanced-2-directory.png b/admin_manual/images/ldap-advanced-2-directory.png index 4fd901d0f..701895852 100644 Binary files a/admin_manual/images/ldap-advanced-2-directory.png and b/admin_manual/images/ldap-advanced-2-directory.png differ diff --git a/admin_manual/images/users-actions.png b/admin_manual/images/users-actions.png new file mode 100644 index 000000000..d675d5290 Binary files /dev/null and b/admin_manual/images/users-actions.png differ diff --git a/admin_manual/images/users-config-1.png b/admin_manual/images/users-config-1.png index 2ffe28ff7..33f13d550 100644 Binary files a/admin_manual/images/users-config-1.png and b/admin_manual/images/users-config-1.png differ diff --git a/admin_manual/images/users-config-2.png b/admin_manual/images/users-config-2.png index 9d7835f06..65c2b960e 100644 Binary files a/admin_manual/images/users-config-2.png and b/admin_manual/images/users-config-2.png differ diff --git a/admin_manual/images/users-create.png b/admin_manual/images/users-create.png index 9ae386de5..58ea55cbd 100644 Binary files a/admin_manual/images/users-create.png and b/admin_manual/images/users-create.png differ diff --git a/admin_manual/images/users-groups.png b/admin_manual/images/users-groups.png index c7a784607..d6fbb569e 100644 Binary files a/admin_manual/images/users-groups.png and b/admin_manual/images/users-groups.png differ diff --git a/admin_manual/index.rst b/admin_manual/index.rst index 67eec5ef9..7bf48ad27 100644 --- a/admin_manual/index.rst +++ b/admin_manual/index.rst @@ -1,9 +1,6 @@ -============================================================= -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 @@ -22,8 +19,8 @@ Nextcloud server is available: See :doc:`../release_notes` for more information on the different Nextcloud editions. -Nextcloud Videos and Blogs --------------------------- +Videos and Blogs +---------------- See the `official Nextcloud channel `_ @@ -45,8 +42,8 @@ respective manuals: * `Nextcloud Android App`_ * `Nextcloud iOS App`_ -.. _`Nextcloud User Manual`: https://docs.nextcloud.com/server/11/user_manual/ -.. _`Nextcloud/ownCloud Desktop Client`: https://doc.owncloud.org/desktop/2.2/ +.. _`Nextcloud User Manual`: https://docs.nextcloud.com/server/12/user_manual/ +.. _`Nextcloud/ownCloud Desktop Client`: https://doc.owncloud.org/desktop/2.3/ .. _`Nextcloud Android App`: https://docs.nextcloud.com/android/ .. _`Nextcloud iOS App`: https://docs.nextcloud.com/ios/ diff --git a/admin_manual/installation/apps_management_installation.rst b/admin_manual/installation/apps_management_installation.rst index 84318337f..8d387def0 100644 --- a/admin_manual/installation/apps_management_installation.rst +++ b/admin_manual/installation/apps_management_installation.rst @@ -8,7 +8,7 @@ applications. Supported Apps -------------- -See :doc:`apps_supported` for a list of supported Enterprise edition apps. +See :doc:`apps_supported` for a list of supported apps. Viewing Enabled Apps -------------------- @@ -42,9 +42,6 @@ page by default. Click the app name to view a description of the app and any of the app settings in the Application View field. Clicking the **Enable** button will enable the app. If the app is not part of the Nextcloud installation, it will be downloaded from the app store, installed and enabled. -Click the gear icon on the lower left to browse experimental apps in the `ownCloud Apps -Store `_. Install experimental apps at your own risk. - Sometimes the installation of a third-party app fails silently, possibly because ``'appcodechecker' => true,`` is enabled in ``config.php``. When ``appcodechecker`` is enabled it checks if third-party apps are using the private API, rather than the public @@ -52,7 +49,7 @@ API. If they are then they will not be installed. .. note:: If you would like to create or add your own Nextcloud app, please refer to the `developer manual - `_. + `_. .. TODO ON RELEASE: Update version number above on release Using Custom App Directories diff --git a/admin_manual/installation/apps_supported.rst b/admin_manual/installation/apps_supported.rst index 2f20e5b05..846d5f8e3 100644 --- a/admin_manual/installation/apps_supported.rst +++ b/admin_manual/installation/apps_supported.rst @@ -1,25 +1,25 @@ -=========================== -Supported Apps in Nextcloud -=========================== +============== +Supported Apps +============== -AGPL Apps ---------- +Below is the list of apps supported for Nextcloud |version|. Supported here means that we'll accept bugreports and resolve them in these apps with regard to functionality and compatibility with Nextcloud |version|. To get access to work-arounds, long term support, priority bug fixing and custom consulting, contact Nextcloud GmbH. * Activity * Admin Audit Log * AntiVirus * Calendar +* Circles * Collaborative Tags * Comments * Contacts * Encryption * External Sites -* External Storage * Federated File Sharing (allows file sharing across Nextcloud instances) * Federation (allows usernname auto-complete across Nextcloud instances) * Files (cannot be disabled) * Files Access Control * Files Automated Tagging +* Files External (external storage) * Files PDF Viewer * Files Sharing * Files Text Editor @@ -28,15 +28,26 @@ AGPL Apps * Files Video Player * First Run Wizard * Gallery +* Logreader +* Lookup Server Connector +* Nextant +* Nextcloud Announcements * Notifications * Object Storage (Swift) * Password Policy * Provisioning API +* Server info (monitoring app) +* Sharebymail +* Socialsharing (Diaspora, email, Facebook, Google+ and Twitter) +* Sharepoint (external storage) * Template Editor (for notification emails) * Theming * Update Notifications * User External * User LDAP * User Shibboleth/SAML +* Video Calls (former Spreed) * WebDAV Endpoint (handles old and new webdav endpoints) * Workflow Engine (cannot be disabled) + +All apps are licensed under the AGPL. diff --git a/admin_manual/installation/command_line_installation.rst b/admin_manual/installation/command_line_installation.rst index 6111d5304..3b5f3a4da 100644 --- a/admin_manual/installation/command_line_installation.rst +++ b/admin_manual/installation/command_line_installation.rst @@ -1,6 +1,6 @@ -========================================== -Installing Nextcloud from the Command Line -========================================== +============================ +Installing from Command Line +============================ It is now possible to install Nextcloud entirely from the command line. This is convenient for scripted operations, headless servers, and sysadmins who prefer @@ -38,11 +38,6 @@ Supported databases are:: See :ref:`command_line_installation_label` for more information. -Finally, apply the correct strong permissions to your Nextcloud files and -directories (see :ref:`strong_perms_label`). This is an extremely important -step. It helps protect your Nextcloud installation, and ensures that it will run -correctly. - BINLOG_FORMAT = STATEMENT ------------------------- diff --git a/admin_manual/installation/deployment_recommendations.rst b/admin_manual/installation/deployment_recommendations.rst index f43d65111..4608834e8 100644 --- a/admin_manual/installation/deployment_recommendations.rst +++ b/admin_manual/installation/deployment_recommendations.rst @@ -1,6 +1,6 @@ -==================================== -Nextcloud Deployment Recommendations -==================================== +========================== +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 @@ -414,7 +414,7 @@ Provider setup: * 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) - HAProxy or `MaxScale`_ are possible proxy + requests accordingly (2-n) - `MaxScale`_ is a 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 @@ -456,8 +456,6 @@ 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 ----------------------- @@ -553,11 +551,11 @@ References .. TODO ON RELEASE: Update version number below on release .. _Maintenance: - https://docs.nextcloud.org/server/11/admin_manual/maintenance/index.html + https://docs.nextcloud.org/server/12/admin_manual/maintenance/index.html .. _User Authentication with LDAP: - https://docs.nextcloud.org/server/11/admin_manual/configuration_user/user_auth_ldap.html + https://docs.nextcloud.org/server/12/admin_manual/configuration_user/user_auth_ldap.html .. _Configuring Memory Caching: - https://docs.nextcloud.org/server/11/admin_manual/configuration_server/caching_configuration.html + https://docs.nextcloud.org/server/12/admin_manual/configuration_server/caching_configuration.html .. _Nextcloud Server or Enterprise Edition: https://nextcloud.com/enterprise/ @@ -579,8 +577,6 @@ References 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: diff --git a/admin_manual/installation/index.rst b/admin_manual/installation/index.rst index ce4a9e19e..1c4c72f19 100644 --- a/admin_manual/installation/index.rst +++ b/admin_manual/installation/index.rst @@ -15,5 +15,4 @@ Installation php_56_installation php_70_installation selinux_configuration - nginx_examples - nginx_nextcloud_9x + nginx diff --git a/admin_manual/installation/installation_wizard.rst b/admin_manual/installation/installation_wizard.rst index 1544a3be2..a217da5ab 100644 --- a/admin_manual/installation/installation_wizard.rst +++ b/admin_manual/installation/installation_wizard.rst @@ -22,14 +22,11 @@ You're finished and can start using your new Nextcloud server. Of course, there is much more that you can do to set up your Nextcloud server for best performance and security. In the following sections we will cover important -installation and post-installation steps. Note that you must follow the -instructions in :ref:`Setting Strong Permissions ` in order -to use the :doc:`occ Command <../configuration_server/occ_command>`. +installation and post-installation steps. * :ref:`Data Directory Location ` * :ref:`Database Choice ` * :ref:`Trusted Domains ` -* :ref:`Setting Strong Permissions ` .. _data_directory_location_label: @@ -49,8 +46,7 @@ Nextcloud data in a different location for other reasons (e.g. on a storage server). It is best to configure your data directory location at installation, as it is difficult to move after installation. You may put it anywhere; in this example is it located in ``/var/oc_data``. This directory must already exist, -and must be owned by your HTTP user (see -:ref:`strong_perms_label`). +and must be owned by your HTTP user. .. _database_choice_label: @@ -113,94 +109,3 @@ is not whitelisted the following error appears: .. figure:: images/install-wizard-a4.png :scale: 75% :alt: Error message when URL is not whitelisted - -.. _strong_perms_label: - -Setting Strong Directory Permissions ------------------------------------- - -For hardened security we recommend setting the permissions on your Nextcloud -directories as strictly as possible. This should be done immediately after the -initial installation and before running the setup. Your HTTP user must own the -``config/``, ``data/`` and ``apps/`` directories so that you can configure -Nextcloud, create, modify and delete your data files, and install apps via the -Nextcloud Web interface. - -You can find your HTTP user in your HTTP server configuration files. Or you can -use :ref:`label-phpinfo` (Look for the **User/Group** line). - -* The HTTP user and group in Debian/Ubuntu is ``www-data``. -* The HTTP user and group in Fedora/CentOS is ``apache``. -* The HTTP user and group in Arch Linux is ``http``. -* The HTTP user in openSUSE is ``wwwrun``, and the HTTP group is ``www``. - -.. note:: When using an NFS mount for the data directory, do not change its - ownership from the default. The simple act of mounting the drive will set - proper permissions for Nextcloud to write to the directory. Changing - ownership as above could result in some issues if the NFS mount is - lost. - -The easy way to set the correct permissions is to copy and run this script. -Replace the ``ocpath`` variable with the path to your Nextcloud directory, and -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/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 - - printf "chown Directories\n" - chown -R ${rootuser}:${htgroup} ${ocpath}/ - chown -R ${htuser}:${htgroup} ${ocpath}/apps/ - chown -R ${htuser}:${htgroup} ${ocpath}/config/ - chown -R ${htuser}:${htgroup} ${datapath} - chown -R ${htuser}:${htgroup} ${ocpath}/themes/ - chown -R ${htuser}:${htgroup} ${ocpath}/updater/ - - chmod +x ${ocpath}/occ - - printf "chmod/chown .htaccess\n" - if [ -f ${ocpath}/.htaccess ] - then - chmod 0644 ${ocpath}/.htaccess - chown ${rootuser}:${htgroup} ${ocpath}/.htaccess - fi - if [ -f ${datapath}/.htaccess ] - then - chmod 0644 ${datapath}/.htaccess - chown ${rootuser}:${htgroup} ${datapath}/.htaccess - fi - -If you have customized your Nextcloud installation and your filepaths are -different than the standard installation, then modify this script accordingly. - -This lists the recommended modes and ownership for your Nextcloud directories -and files: - -* All files should be read-write for the file owner, read-only for the - group owner, and zero for the world -* All directories should be executable (because directories always need the - executable bit set), read-write for the directory owner, and read-only for - the group owner -* 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:`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]`` -* Both :file:`.htaccess` files are read-write file owner, read-only group and - world - -These strong permissions prevent upgrading your Nextcloud server; -see :ref:`set_updating_permissions_label` for a script to quickly change -permissions to allow upgrading. diff --git a/admin_manual/installation/nginx_nextcloud_9x.rst b/admin_manual/installation/nginx.rst similarity index 59% rename from admin_manual/installation/nginx_nextcloud_9x.rst rename to admin_manual/installation/nginx.rst index 152f3102d..c5f086a84 100644 --- a/admin_manual/installation/nginx_nextcloud_9x.rst +++ b/admin_manual/installation/nginx.rst @@ -2,21 +2,35 @@ 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 -the examples, as long lines may be broken for page formatting. +This page covers example Nginx configurations to use with running an Nextcloud +server. This page is community-maintained. (Thank you, contributors!) -Some environments might need a ``cgi.fix_pathinfo`` set to ``1`` in their -``php.ini``. +- You need to insert the following code into **your Nginx configuration file.** +- Adjust **server_name**, **root**, **ssl_certificate** and + **ssl_certificate_key** to suit your needs. +- Make sure your SSL certificates are readable by the server (see `nginx HTTP + SSL Module documentation `_). +- ``add_header`` statements are only taken from the current level and are not + cascaded from or to a different level. All necessary ``add_header`` + statements must be defined in each level needed. For better readability it + is possible to move *common* add header statements into a separate file + and include that file wherever necessary. However, each ``add_header`` + statement must be written in a single line to prevent connection problems + with sync clients. +- Be careful about line breaks if you copy the examples, as long lines may be + broken for page formatting. +- Some environments might need a ``cgi.fix_pathinfo`` set to ``1`` in their + ``php.ini``. -Thanks to `@josh4trunks `_ for providing / +Thanks to `@josh4trunks `_ for providing / creating these configuration examples. Nextcloud in the webroot of nginx --------------------------------- -The following config should be used when Nextcloud is placed in the webroot of -your nginx installation. +The following configuration should be used when Nextcloud is placed in the +webroot of your nginx installation. In this example it is +``/var/www/nextcloud`` and it is accessed via ``http(s)://cloud.example.com`` .. code-block:: nginx @@ -31,105 +45,117 @@ your nginx installation. # enforce https return 301 https://$server_name$request_uri; } - + server { - listen 443 ssl; + listen 443 ssl http2; server_name cloud.example.com; - + ssl_certificate /etc/ssl/nginx/cloud.example.com.crt; ssl_certificate_key /etc/ssl/nginx/cloud.example.com.key; - + # Add headers to serve security related headers - # Before enabling Strict-Transport-Security headers please read into this + # Before enabling Strict-Transport-Security headers please read into this # topic first. - # add_header Strict-Transport-Security "max-age=15768000; + # add_header Strict-Transport-Security "max-age=15768000; # includeSubDomains; preload;"; + # + # WARNING: Only add the preload option once you read about + # the consequences in https://hstspreload.org/. This option + # will add the domain to a hardcoded list that is shipped + # in all major browsers and getting removed from this list + # could take several months. add_header X-Content-Type-Options nosniff; - add_header X-Frame-Options "SAMEORIGIN"; add_header X-XSS-Protection "1; mode=block"; add_header X-Robots-Tag none; add_header X-Download-Options noopen; add_header X-Permitted-Cross-Domain-Policies none; - + # Path to the root of your installation root /var/www/nextcloud/; - + location = /robots.txt { allow all; log_not_found off; access_log off; } - + # The following 2 rules are only needed for the user_webfinger app. # Uncomment it if you're planning to use this app. #rewrite ^/.well-known/host-meta /public.php?service=host-meta last; - #rewrite ^/.well-known/host-meta.json /public.php?service=host-meta-json + #rewrite ^/.well-known/host-meta.json /public.php?service=host-meta-json # last; - - location = /.well-known/carddav { + + location = /.well-known/carddav { return 301 $scheme://$host/remote.php/dav; } location = /.well-known/caldav { return 301 $scheme://$host/remote.php/dav; } - + # set max upload size client_max_body_size 512M; fastcgi_buffers 64 4K; - - # Disable gzip to avoid the removal of the ETag header - gzip off; - + + # Enable gzip but do not remove ETag headers + gzip on; + gzip_vary on; + gzip_comp_level 4; + gzip_min_length 256; + gzip_proxied expired no-cache no-store private no_last_modified no_etag auth; + gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy; + # Uncomment if your server is build with the ngx_pagespeed module # 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; } - + location ~ ^/(?:build|tests|config|lib|3rdparty|templates|data)/ { deny all; } location ~ ^/(?:\.|autotest|occ|issue|indie|db_|console) { deny all; } - - location ~ ^/(?:index|remote|public|cron|core/ajax/update|status|ocs/v[12]|updater/.+|ocs-provider/.+|core/templates/40[34])\.php(?:$|/) { + + location ~ ^/(?:index|remote|public|cron|core/ajax/update|status|ocs/v[12]|updater/.+|ocs-provider/.+)\.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; #Avoid sending the security headers twice - fastcgi_param modHeadersAvailable true; + fastcgi_param modHeadersAvailable true; fastcgi_param front_controller_active true; fastcgi_pass php-handler; fastcgi_intercept_errors on; fastcgi_request_buffering off; } - + location ~ ^/(?:updater|ocs-provider)(?:$|/) { try_files $uri/ =404; index index.php; } - + # Adding the cache control header for js and css files # Make sure it is BELOW the PHP block - location ~* \.(?:css|js|woff|svg|gif)$ { + location ~ \.(?:css|js|woff|svg|gif)$ { try_files $uri /index.php$uri$is_args$args; - add_header Cache-Control "public, max-age=7200"; - # Add headers to serve security related headers (It is intended to + add_header Cache-Control "public, max-age=15778463"; + # Add headers to serve security related headers (It is intended to # have those duplicated to the ones above) - # Before enabling Strict-Transport-Security headers please read into + # Before enabling Strict-Transport-Security headers please read into # this topic first. - # add_header Strict-Transport-Security "max-age=15768000; + # add_header Strict-Transport-Security "max-age=15768000; # includeSubDomains; preload;"; + # + # WARNING: Only add the preload option once you read about + # the consequences in https://hstspreload.org/. This option + # will add the domain to a hardcoded list that is shipped + # in all major browsers and getting removed from this list + # could take several months. add_header X-Content-Type-Options nosniff; - add_header X-Frame-Options "SAMEORIGIN"; add_header X-XSS-Protection "1; mode=block"; add_header X-Robots-Tag none; add_header X-Download-Options noopen; @@ -137,8 +163,8 @@ your nginx installation. # Optional: Don't log access to assets access_log off; } - - location ~* \.(?:png|html|ttf|ico|jpg|jpeg)$ { + + location ~ \.(?:png|html|ttf|ico|jpg|jpeg)$ { try_files $uri /index.php$uri$is_args$args; # Optional: Don't log access to other assets access_log off; @@ -148,7 +174,7 @@ your nginx installation. Nextcloud in a subdir of nginx ------------------------------ -The following config should be used when Nextcloud is placed within a subdir of +The following config should be used when Nextcloud is placed within a subdir of your nginx installation. .. code-block:: nginx @@ -157,47 +183,46 @@ your nginx installation. server 127.0.0.1:9000; #server unix:/var/run/php5-fpm.sock; } - + server { listen 80; server_name cloud.example.com; # enforce https return 301 https://$server_name$request_uri; } - + server { - listen 443 ssl; + listen 443 ssl http2; server_name cloud.example.com; - + ssl_certificate /etc/ssl/nginx/cloud.example.com.crt; ssl_certificate_key /etc/ssl/nginx/cloud.example.com.key; - + # Add headers to serve security related headers - # Before enabling Strict-Transport-Security headers please read into this + # Before enabling Strict-Transport-Security headers please read into this # topic first. - #add_header Strict-Transport-Security "max-age=15768000; + #add_header Strict-Transport-Security "max-age=15768000; # includeSubDomains; preload;"; add_header X-Content-Type-Options nosniff; - add_header X-Frame-Options "SAMEORIGIN"; add_header X-XSS-Protection "1; mode=block"; add_header X-Robots-Tag none; add_header X-Download-Options noopen; add_header X-Permitted-Cross-Domain-Policies none; - + # Path to the root of your installation root /var/www/; - + location = /robots.txt { allow all; log_not_found off; access_log off; } - + # The following 2 rules are only needed for the user_webfinger app. # Uncomment it if you're planning to use this app. - # rewrite ^/.well-known/host-meta /nextcloud/public.php?service=host-meta + # rewrite ^/.well-known/host-meta /nextcloud/public.php?service=host-meta # last; - #rewrite ^/.well-known/host-meta.json + #rewrite ^/.well-known/host-meta.json # /nextcloud/public.php?service=host-meta-json last; location = /.well-known/carddav { @@ -208,23 +233,25 @@ your nginx installation. } location /.well-known/acme-challenge { } - + location ^~ /nextcloud { - + # set max upload size client_max_body_size 512M; fastcgi_buffers 64 4K; - - # Disable gzip to avoid the removal of the ETag header - gzip off; - + + # Enable gzip but do not remove ETag headers + gzip on; + gzip_vary on; + gzip_comp_level 4; + gzip_min_length 256; + gzip_proxied expired no-cache no-store private no_last_modified no_etag auth; + gzip_types application/atom+xml application/javascript application/json application/ld+json application/manifest+json application/rss+xml application/vnd.geo+json application/vnd.ms-fontobject application/x-font-ttf application/x-web-app-manifest+json application/xhtml+xml application/xml font/opentype image/bmp image/svg+xml image/x-icon text/cache-manifest text/css text/plain text/vcard text/vnd.rim.location.xloc text/vtt text/x-component text/x-cross-domain-policy; + # 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; } @@ -236,38 +263,37 @@ your nginx installation. deny all; } - location ~ ^/nextcloud/(?:index|remote|public|cron|core/ajax/update|status|ocs/v[12]|updater/.+|ocs-provider/.+|core/templates/40[34])\.php(?:$|/) { + location ~ ^/nextcloud/(?:index|remote|public|cron|core/ajax/update|status|ocs/v[12]|updater/.+|ocs-provider/.+)\.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; - #Avoid sending the security headers twice - fastcgi_param modHeadersAvailable true; + #Avoid sending the security headers twice + fastcgi_param modHeadersAvailable true; fastcgi_param front_controller_active true; fastcgi_pass php-handler; fastcgi_intercept_errors on; fastcgi_request_buffering off; } - + location ~ ^/nextcloud/(?:updater|ocs-provider)(?:$|/) { try_files $uri/ =404; index index.php; } - + # Adding the cache control header for js and css files # Make sure it is BELOW the PHP block - location ~* \.(?:css|js|woff|svg|gif)$ { + location ~ \.(?:css|js|woff|svg|gif)$ { try_files $uri /nextcloud/index.php$uri$is_args$args; - add_header Cache-Control "public, max-age=7200"; - # Add headers to serve security related headers (It is intended + add_header Cache-Control "public, max-age=15778463"; + # Add headers to serve security related headers (It is intended # to have those duplicated to the ones above) - # Before enabling Strict-Transport-Security headers please read + # Before enabling Strict-Transport-Security headers please read # into this topic first. - # add_header Strict-Transport-Security "max-age=15768000; + # add_header Strict-Transport-Security "max-age=15768000; # includeSubDomains; preload;"; add_header X-Content-Type-Options nosniff; - add_header X-Frame-Options "SAMEORIGIN"; add_header X-XSS-Protection "1; mode=block"; add_header X-Robots-Tag none; add_header X-Download-Options noopen; @@ -275,12 +301,51 @@ your nginx installation. # Optional: Don't log access to assets access_log off; } - - location ~* \.(?:png|html|ttf|ico|jpg|jpeg)$ { + + location ~ \.(?:png|html|ttf|ico|jpg|jpeg)$ { try_files $uri /nextcloud/index.php$uri$is_args$args; # Optional: Don't log access to other assets access_log off; } } } - + +Tips and Tricks +--------------- + +Suppressing Log Messages +======================== + +If you're seeing meaningless messages in your logfile, for example ``client +denied by server configuration: /var/www/data/htaccesstest.txt``, add this section to +your nginx configuration to suppress them: + +.. code-block:: nginx + + location = /data/htaccesstest.txt { + allow all; + log_not_found off; + access_log off; + } + +JavaScript (.js) or CSS (.css) files not served properly +======================================================== + +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: + +.. code-block:: nginx + + location ~* \.(?:css|js)$ { + +block shown above not located **below** the: + +.. code-block:: nginx + + location ~ \.php(?:$|/) { + +block. Other custom configurations like caching JavaScript (.js) +or CSS (.css) files via gzip could also cause such issues. diff --git a/admin_manual/installation/nginx_examples.rst b/admin_manual/installation/nginx_examples.rst deleted file mode 100644 index 0ea7a6997..000000000 --- a/admin_manual/installation/nginx_examples.rst +++ /dev/null @@ -1,334 +0,0 @@ -============================ -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!) - - -- You need to insert the following code into **your Nginx configuration file.** -- The configuration assumes that Nextcloud is installed in - ``/var/www/nextcloud`` and that it is accessed via - ``http(s)://cloud.example.com``. -- Adjust **server_name**, **root**, **ssl_certificate** and - **ssl_certificate_key** to suit your needs. -- Make sure your SSL certificates are readable by the server (see `nginx HTTP - SSL Module documentation `_). -- ``add_header`` statements are only taken from the current level and are not - cascaded from or to a different level. All necessary ``add_header`` - statements must be defined in each level needed. For better readability it - is possible to move *common* add header statements into a separate file - and include that file wherever necessary. However, each ``add_header`` - statement must be written in a single line to prevent connection problems - with sync clients. - -Example Configurations ----------------------- - -- :doc:`nginx_nextcloud_9x` - -You can use Nextcloud over plain http, but we strongly encourage you to use -SSL/TLS to encrypt all of your server traffic, and to protect user's logins and -data in transit. - -- Remove the server block containing the redirect -- Change **listen 443 ssl** to **listen 80;** -- Remove **ssl_certificate** and **ssl_certificate_key**. -- Remove **fastcgi_params HTTPS on;** - -Suppressing Log Messages -======================== - -If you're seeing meaningless messages in your logfile, for example `client -denied by server configuration: /var/www/data/htaccesstest.txt -`_, add this section to -your nginx configuration to suppress them: - -.. code-block:: nginx - - location = /data/htaccesstest.txt { - allow all; - log_not_found off; - access_log off; - } - -JavaScript (.js) or CSS (.css) files not served properly -======================================================== - -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: - -.. code-block:: nginx - - location ~* \.(?:css|js)$ { - -block shown above not located **below** the: - -.. code-block:: nginx - - location ~ \.php(?:$|/) { - -block. Other custom configurations like caching JavaScript (.js) -or CSS (.css) files via gzip could also cause such issues. - -Performance Tuning -================== - -* `nginx (<1.9.5) `_ -* `nginx (+1.9.5) `_ - -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. - -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 -=========================================== - -One of the optimizations for Nextcloud when using nginx as the Web server is to -combine FastCGI caching with "Cache Purge", a `3rdparty nginx module -`_ that adds the ability to purge -content from `FastCGI`, `proxy`, `SCGI` and `uWSGI` caches. This mechanism -speeds up thumbnail presentation as it shifts requests to nginx and minimizes -php invocations which otherwise would take place for every thumbnail presented -every time. - -The following procedure is based on an Ubuntu 14.04 system. You may need to -adapt it according your OS type and release. - -.. note:: - Unlike Apache, nginx does not dynamically load modules. All modules needed - must be compiled into nginx. This is one of the reasons for nginx´s - performance. It is expected to have an already running nginx installation - with a working configuration set up as described in the Nextcloud - documentation. - -nginx module check -================== - -As a first step, it is necessary to check if your nginx installation has the -``nginx cache purge`` module compiled in:: - - nginx -V 2>&1 | grep ngx_cache_purge -o - -If your output contains ``ngx_cache_purge``, you can continue with the -configuration, otherwise you need to manually compile nginx with the module -needed. - -Compile nginx with the ``nginx-cache-purge`` module -=================================================== - -1. **Preparation:** - -:: - - cd /opt - wget http://nginx.org/keys/nginx_signing.key - sudo apt-key add nginx_signing.key - sudo vi /etc/apt/sources.list.d/nginx.list - -Add the following lines (if different, replace ``{trusty}`` by your -distribution name):: - - deb http://nginx.org/packages/mainline/ubuntu/ trusty nginx - deb -src http://nginx.org/packages/mainline/ubuntu/ trusty nginx - -Then run ``sudo apt-get update`` - -.. note:: If you're not overly cautious and wish to install the latest and - greatest nginx packages and features, you may have to install nginx from its - mainline repository. From the nginx homepage: "In general, you should - deploy nginx from its mainline branch at all times." If you would like to - use standard nginx from the latest mainline branch but without compiling in - any additional modules, just run ``sudo apt-get install nginx``. - -2. **Download the nginx source from the ppa repository** - -:: - - cd /opt - sudo apt-get build-dep nginx - sudo apt-get source nginx - -3. **Download module(s) to be compiled in and configure compiler arguments** - -:: - - ls -la - -Please replace ``{release}`` with the release downloaded:: - - cd /opt/nginx-{release}/debian - -If folder "modules" is not present, do: - -:: - - sudo mkdir modules - cd modules - sudo git clone https://github.com/FRiCKLE/ngx_cache_purge.git - sudo vi /opt/nginx-{release}/debian/rules - -If not present, add the following line at the top under:: - - #export DH_VERBOSE=1: - MODULESDIR = $(CURDIR)/debian/modules - -And at the end of every ``configure`` command add:: - - --add-module=$(MODULESDIR)/ngx_cache_purge - -Don't forget to escape preceding lines with a backslash ``\``. -The parameters may now look like:: - - --with-cc-opt="$(CFLAGS)" \ - --with-ld-opt="$(LDFLAGS)" \ - --with-ipv6 \ - --add-module=$(MODULESDIR)/ngx_cache_purge - -4. **Compile and install nginx** - -:: - - cd /opt/nginx-{release} - sudo dpkg-buildpackage -uc -b - ls -la /opt - sudo dpkg --install /opt/nginx_{release}~{distribution}_amd64.deb - -5. **Check if the compilation and installation of the ngx_cache_purge module - was successful** - -:: - - nginx -V 2>&1 | grep ngx_cache_purge -o - -It should now show: ``ngx_cache_purge`` - -Show nginx version including all features compiled and installed:: - - nginx -V 2>&1 | sed s/" --"/"\n\t--"/g - -6. **Mark nginx to be blocked from further updates via apt-get** - -:: - - sudo dpkg --get-selections | grep nginx - -For every nginx component listed run ``sudo apt-mark hold `` - -7. **Regular checks for nginx updates** - -Do a regular visit on the `nginx news page `_ and proceed -in case of updates with items 2 to 5. - -Configure nginx with the ``nginx-cache-purge`` module -===================================================== - -1. **Preparation** - Create a directory where nginx will save the cached thumbnails. Use any - path that fits to your environment. Replace ``{path}`` in this example with - your path created: - -:: - - sudo mkdir -p /usr/local/tmp/cache - -2. **Configuration** - -:: - - sudo vi /etc/nginx/sites-enabled/{your-nextcloud-nginx-config-file} - -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; - map $request_uri $skip_cache { - default 1; - ~*/thumbnail.php 0; - ~*/apps/galleryplus/ 0; - ~*/apps/gallery/ 0; - } - -.. 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: - - .. 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: - -.. 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; - fastcgi_cache_use_stale error timeout invalid_header http_500; - fastcgi_ignore_headers Cache-Control Expires Set-Cookie; - - location ~ \.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; - fastcgi_no_cache $skip_cache; - fastcgi_cache NEXTCLOUD; - fastcgi_cache_valid 60m; - fastcgi_cache_methods GET HEAD; - } - -.. 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: - - .. code-block:: nginx - - upstream php-handler { - server unix:/var/run/php5-fpm.sock; - # or - # server 127.0.0.1:9000; - } - -3. **Test the configuration** - -:: - - sudo nginx -s reload - -* Open your browser and clear your cache. -* Logon to your Nextcloud instance, open the gallery app, move through your - folders and watch while the thumbnails are generated for the first time. -* You may also watch with eg. ``htop`` your system load while the - thumbnails are processed. -* Go to another app or logout and relogon. -* Open the gallery app again and browse to the folders you accessed before. - Your thumbnails should appear more or less immediately. -* ``htop`` will not show up additional load while processing, compared to - the high load before. diff --git a/admin_manual/installation/selinux_configuration.rst b/admin_manual/installation/selinux_configuration.rst index 4ceb8b0b7..6531986cd 100644 --- a/admin_manual/installation/selinux_configuration.rst +++ b/admin_manual/installation/selinux_configuration.rst @@ -4,52 +4,72 @@ SELinux Configuration ===================== -When you have SELinux enabled on your Linux distribution, you may run into -permissions problems after a new Nextcloud installation, and see ``permission -denied`` errors in your Nextcloud logs. +When you have SELinux enabled on your Linux distribution, you may run into +permissions problems after a new Nextcloud installation, and see ``permission +denied`` errors in your Nextcloud logs. -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 +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 -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 + semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/nextcloud/.htaccess' + semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/nextcloud/.user.ini' + + restorecon -Rv '/var/www/html/nextcloud/' + +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 -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' + semanage fcontext -d '/var/www/html/nextcloud/data(/.*)?' + semanage fcontext -d '/var/www/html/nextcloud/config(/.*)?' + semanage fcontext -d '/var/www/html/nextcloud/apps(/.*)?' + semanage fcontext -d '/var/www/html/nextcloud/.htaccess' + semanage fcontext -d '/var/www/html/nextcloud/.user.ini' -If you have customized SELinux policies and these examples do not work, you must give the + restorecon -Rv '/var/www/html/nextcloud/' + +If you have customized SELinux policies and these examples do not work, you must give the HTTP server write access to these directories:: /var/www/html/nextcloud/data /var/www/html/nextcloud/config /var/www/html/nextcloud/apps +Enable updates via the web interface +------------------------------------ + +To enable updates via the web interface, you may need this to enable writing to the directories:: + + setsebool httpd_unified on + +When the update is completed, disable write access:: + + setsebool -P httpd_unified off + +Disallow write access to the whole web directory +------------------------------------------------ + +For security reasons it's suggested to disable write access to all folders in /var/www/ (default):: + + setsebool -P httpd_unified off + Allow access to a remote database --------------------------------- An additional setting is needed if your installation is connecting to a remote database:: setsebool -P httpd_can_network_connect_db on - + Allow access to LDAP server --------------------------- Use this setting to allow LDAP connections:: setsebool -P httpd_can_connect_ldap on - + Allow access to remote network ------------------------------ @@ -58,6 +78,13 @@ the app store. To allow this access use the following setting:: setsebool -P httpd_can_network_connect on +Allow access to network memcache +-------------------------------- + +This setting is not required if ``httpd_can_network_connect`` is already on:: + + setsebool -P httpd_can_network_memcache on + Allow access to SMTP/sendmail ----------------------------- @@ -73,11 +100,38 @@ If you have placed your datadir on a CIFS/SMB share use the following setting:: setsebool -P httpd_use_cifs on +Allow access to FuseFS +---------------------- + +If your data folder resides on a Fuse Filesystem (e.g. EncFS etc), this setting is required as well:: + + setsebool -P httpd_use_fusefs on + +Allow access to GPG for Rainloop +-------------------------------- + +If you use a the rainloop webmail client app which supports GPG/PGP, you might need this:: + + setsebool -P httpd_use_gpg on + Troubleshooting --------------- -For general Troubleshooting of SELinux and its profiles try to install the package ``setroubleshoot`` and run:: +For general Troubleshooting of SELinux and its profiles try to install the +package ``setroubleshoot`` and run:: sealert -a /var/log/audit/audit.log > /path/to/mylogfile.txt to get a report which helps you configuring your SELinux profiles. + +Another tool for troubleshooting is to enable a single ruleset for your +Nextcloud directory:: + + semanage fcontext -a -t httpd_sys_rw_content_t '/var/www/html/nextcloud(/.*)?' + restorecon -RF /var/www/html/nextcloud + +It is much stronger security to have a more fine-grained ruleset as in the +examples at the beginning, so use this only for testing and troubleshooting. It +has a similar effect to disabling SELinux, so don't use it on production +systems. + diff --git a/admin_manual/installation/source_installation.rst b/admin_manual/installation/source_installation.rst index 334028987..25251da2b 100644 --- a/admin_manual/installation/source_installation.rst +++ b/admin_manual/installation/source_installation.rst @@ -1,41 +1,76 @@ -============================ -Manual Installation on Linux -============================ +===================== +Installation on Linux +===================== -If there are no packages for your Linux distribution, or you prefer installing -from the source tarball, you can setup Nextcloud from scratch using a classic -LAMP stack (Linux, Apache, MySQL/MariaDB, PHP). This document provides a -complete walk-through for installing Nextcloud on Ubuntu 14.04 LTS Server with -Apache and MariaDB, using `the Nextcloud .tar archive -`_. +If there are no packages for your Linux distribution, you have the option to +install `Snap Packages `_. See +:ref:`snaps_label` +In case you prefer installing from the source tarball, you can setup Nextcloud +from scratch using a classic LAMP stack (Linux, Apache, MySQL/MariaDB, PHP). +This document provides a complete walk-through for installing Nextcloud on +Ubuntu 16.04 LTS Server with Apache and MariaDB, using `the Nextcloud .tar +archive `_. + +* :ref:`vm_label` +* :ref:`snaps_label` * :ref:`prerequisites_label` * :ref:`ubuntu_installation_label` * :ref:`binlog_format_label` * :ref:`apache_configuration_label` -* :ref:`pretty_urls_label` +* :ref:`pretty_urls_label` * :ref:`enabling_ssl_label` * :ref:`installation_wizard_label` -* :ref:`strong_perms_label` * :ref:`selinux_tips_label` * :ref:`php_ini_tips_label` * :ref:`php_fpm_tips_label` * :ref:`other_HTTP_servers_label` -.. note:: Admins of SELinux-enabled distributions such as CentOS, Fedora, and - Red Hat Enterprise Linux may need to set new rules to enable installing +.. note:: Admins of SELinux-enabled distributions such as CentOS, Fedora, and + Red Hat Enterprise Linux may need to set new rules to enable installing Nextcloud. See :ref:`selinux_tips_label` for a suggested configuration. +.. _vm_label: + +Installing on Windows (Virtual Machine) +--------------------------------------- + +If you are using Windows, the easiest way to get Nextcloud up an running is using our Virtual Machine. The VM is mainly maintainted by Tech and Me and are offered in several different versions. The main version is for VMware version 10 and comes in different sizes. The standard size is 20 GB, but you can also download a 500 GB and a 1 TB version. Tech and Me also provides a Hyper-V version for all Hyper-V users. + +You can find complete instructions and downloads here: https://github.com/nextcloud/vm or here https://www.techandme.se/nextcloud-vm/ + +Of course you can also install it on other OSes than Windows and you are not limited to any OS really as long as your hypervisor can mount OVA, VMDK, or VHD. + +.. _snaps_label: + +Installing via Snap Packages +---------------------------- + +A snap is a zip file containing an application together with its dependencies, +and a description of how it should safely be run on your system, especially +the different ways it should talk to other software. Most importantly snaps are +designed to be secure, sandboxed, containerised applications isolated from the +underlying system and from other applications. + +To install the Nextcloud Snap Package, run the following command in a terminal:: + + sudo snap install nextcloud + +.. note:: The `snapd technology `_ is the core + that powers snaps, and it offers a new way to package, distribute, update and + run OS components and applications on a Linux system. See more about snaps on + `snapcraft.io `_. + .. _prerequisites_label: -Prerequisites -------------- +Prerequisites for Manual Installation +------------------------------------- -The Nextcloud .tar archive contains all of the required PHP modules. This -section lists all required and optional PHP modules. Consult the `PHP manual -`_ for more information on modules. -Your Linux distribution should have packages for all required modules. You can -check the presence of a module by typing ``php -m | grep -i ``. +The Nextcloud .tar archive contains all of the required PHP modules. This +section lists all required and optional PHP modules. Consult the `PHP manual +`_ for more information on modules. +Your Linux distribution should have packages for all required modules. You can +check the presence of a module by typing ``php -m | grep -i ``. If you get a result, the module is present. Required: @@ -67,7 +102,7 @@ Database connectors (pick the one for your database:) authentication, depends on this) * PHP module fileinfo (highly recommended, enhances file analysis performance) * PHP module bz2 (recommended, required for extraction of apps) -* PHP module intl (increases language translation performance and fixes sorting +* PHP module intl (increases language translation performance and fixes sorting of non-ASCII characters) * PHP module mcrypt (increases file encryption performance) * PHP module openssl (required for accessing HTTPS resources) @@ -75,7 +110,7 @@ Database connectors (pick the one for your database:) Required for specific apps: * PHP module ldap (for LDAP integration) -* PHP module smbclient (SMB/CIFS integration, see +* PHP module smbclient (SMB/CIFS integration, see :doc:`../configuration_files/external_storage/smb`) * PHP module ftp (for FTP storage / external user authentication) * PHP module imap (for external user authentication) @@ -85,14 +120,14 @@ Recommended for specific apps (*optional*): * PHP module exif (for image rotation in pictures app) * PHP module gmp (for SFTP storage) -For enhanced server performance (*optional*) select one of the following +For enhanced server performance (*optional*) select one of the following memcaches: * PHP module apcu (>= 4.0.6) * PHP module memcached * PHP module redis (>= 2.2.6, required for Transactional File Locking) -See :doc:`../configuration_server/caching_configuration` to learn how to select +See :doc:`../configuration_server/caching_configuration` to learn how to select and configure a memcache. For preview generation (*optional*): @@ -105,47 +140,54 @@ For command line processing (*optional*): * PHP module pcntl (enables command interruption by pressing ``ctrl-c``) -You don’t need the WebDAV module for your Web server (i.e. Apache’s +You don’t need the WebDAV module for your Web server (i.e. Apache’s ``mod_webdav``), as Nextcloud has a built-in WebDAV server of its own, SabreDAV. -If ``mod_webdav`` is enabled you must disable it for Nextcloud. (See +If ``mod_webdav`` is enabled you must disable it for Nextcloud. (See :ref:`apache_configuration_label` for an example configuration.) - + .. _ubuntu_installation_label: Example Installation on Ubuntu 16.04 LTS Server ----------------------------------------------- -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:: +On a machine running a pristine Ubuntu 16.04 LTS server, you have two options: + +You can either install the Nextcloud `Snap Package `_, just run the +following command in a terminal:: + + sudo snap install nextcloud + +Or you can use .deb packages to 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-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-php7.0`` provides the following PHP extensions: ``bcmath bz2 - calendar Core ctype date dba dom ereg exif fileinfo filter ftp gettext hash - iconv libxml mhash openssl pcre Phar posix Reflection session shmop - SimpleXML soap sockets SPL standard sysvmsg sysvsem sysvshm tokenizer wddx - xmlreader xmlwriter zlib``. If you are planning - on running additional apps, keep in mind that they might require additional +* This installs the packages for the Nextcloud core system. + ``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 mhash openssl pcre Phar posix Reflection session shmop + SimpleXML soap sockets SPL standard sysvmsg sysvsem sysvshm tokenizer wddx + 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. -* At the installation of the MySQL/MariaDB server, you will be prompted to - create a root password. Be sure to remember your password as you will need it +* At the installation of the MySQL/MariaDB server, you will be prompted to + create a root password. Be sure to remember your password as you will need it during Nextcloud database setup. Now download the archive of the latest Nextcloud version: * Go to the `Nextcloud Download Page `_. -* Go to **Download Nextcloud Server > Download > Archive file for +* Go to **Download Nextcloud Server > Download > Archive file for server owners** and download either the tar.bz2 or .zip archive. -* This downloads a file named nextcloud-x.y.z.tar.bz2 or nextcloud-x.y.z.zip +* This downloads a file named nextcloud-x.y.z.tar.bz2 or nextcloud-x.y.z.zip (where x.y.z is the version number). -* Download its corresponding checksum file, e.g. nextcloud-x.y.z.tar.bz2.md5, - or nextcloud-x.y.z.tar.bz2.sha256. +* Download its corresponding checksum file, e.g. nextcloud-x.y.z.tar.bz2.md5, + or nextcloud-x.y.z.tar.bz2.sha256. * Verify the MD5 or SHA256 sum:: md5sum -c nextcloud-x.y.z.tar.bz2.md5 < nextcloud-x.y.z.tar.bz2 @@ -159,25 +201,25 @@ Now download the archive of the latest Nextcloud version: wget https://nextcloud.com/nextcloud.asc gpg --import nextcloud.asc gpg --verify nextcloud-x.y.z.tar.bz2.asc nextcloud-x.y.z.tar.bz2 - -* Now you can extract the archive contents. Run the appropriate unpacking + +* Now you can extract the archive contents. Run the appropriate unpacking command for your archive type:: tar -xjf nextcloud-x.y.z.tar.bz2 unzip nextcloud-x.y.z.zip -* This unpacks to a single ``nextcloud`` directory. Copy the Nextcloud directory - to its final destination. When you are running the Apache HTTP server you may +* This unpacks to a single ``nextcloud`` directory. Copy the Nextcloud directory + to its final destination. When you are running the Apache HTTP server you may safely install Nextcloud in your Apache document root:: cp -r nextcloud /path/to/webserver/document-root - where ``/path/to/webserver/document-root`` is replaced by the + where ``/path/to/webserver/document-root`` is replaced by the document root of your Web server:: cp -r nextcloud /var/www -On other HTTP servers it is recommended to install Nextcloud outside of the +On other HTTP servers it is recommended to install Nextcloud outside of the document root. .. _binlog_format_label: @@ -187,11 +229,11 @@ BINLOG_FORMAT = STATEMENT If your Nextcloud installation fails and you see this in your Nextcloud log:: - An unhandled exception has been thrown: exception ‘PDOException’ with message - 'SQLSTATE[HY000]: General error: 1665 Cannot execute statement: impossible to - write to binary log since BINLOG_FORMAT = STATEMENT and at least one table - uses a storage engine limited to row-based logging. InnoDB is limited to - row-logging when transaction isolation level is READ COMMITTED or READ + An unhandled exception has been thrown: exception ‘PDOException’ with message + 'SQLSTATE[HY000]: General error: 1665 Cannot execute statement: impossible to + write to binary log since BINLOG_FORMAT = STATEMENT and at least one table + uses a storage engine limited to row-based logging. InnoDB is limited to + row-logging when transaction isolation level is READ COMMITTED or READ UNCOMMITTED.' See :ref:`db-binlog-label`. @@ -201,9 +243,9 @@ See :ref:`db-binlog-label`. Apache Web Server Configuration ------------------------------- -On Debian, Ubuntu, and their derivatives, Apache installs with a useful -configuration so all you have to do is create a -:file:`/etc/apache2/sites-available/nextcloud.conf` file with these lines in +On Debian, Ubuntu, and their derivatives, Apache installs with a useful +configuration so all you have to do is create a +:file:`/etc/apache2/sites-available/nextcloud.conf` file with these lines in it, replacing the **Directory** and other filepaths with your own filepaths:: Alias /nextcloud "/var/www/nextcloud/" @@ -220,11 +262,11 @@ it, replacing the **Directory** and other filepaths with your own filepaths:: SetEnv HTTP_HOME /var/www/nextcloud - + Then create a symlink to :file:`/etc/apache2/sites-enabled`:: ln -s /etc/apache2/sites-available/nextcloud.conf /etc/apache2/sites-enabled/nextcloud.conf - + Additional Apache Configurations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -232,56 +274,74 @@ Additional Apache Configurations it by running:: a2enmod rewrite - + Additional recommended modules are ``mod_headers``, ``mod_env``, ``mod_dir`` and ``mod_mime``:: - + a2enmod headers a2enmod env a2enmod dir a2enmod mime - + If you're running ``mod_fcgi`` instead of the standard ``mod_php`` also enable:: - + a2enmod setenvif -* You must disable any server-configured authentication for Nextcloud, as it - uses Basic authentication internally for DAV services. If you have turned on - 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 +* You must disable any server-configured authentication for Nextcloud, as it + uses Basic authentication internally for DAV services. If you have turned on + 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 ```` section:: Satisfy Any -* When using SSL, take special note of the ServerName. You should specify one - in the server configuration, as well as in the CommonName field of the - certificate. If you want your Nextcloud to be reachable via the internet, +* When using SSL, take special note of the ServerName. You should specify one + in the server configuration, as well as in the CommonName field of the + certificate. If you want your Nextcloud to be reachable via the internet, then set both of these to the domain you want to reach your Nextcloud server. * Now restart Apache:: service apache2 restart -* If you're running Nextcloud in a subdirectory and want to use CalDAV or - CardDAV clients make sure you have configured the correct +* If you're running Nextcloud in a subdirectory and want to use CalDAV or + CardDAV clients make sure you have configured the correct :ref:`service-discovery-label` URLs. - + .. _pretty_urls_label: - + Pretty URLs ----------- -Pretty URLs are created automatically when ``.htaccess`` is writable by the -HTTP user, ``mod_env`` and ``mod_rewrite`` are installed, and -``'overwrite.cli.url'`` in your ``config.php`` is set to any non-null value. +Pretty URLs remove the ``index.php``-part in all Nextcloud URLs, for example +in sharing links like ``https://example.org/nextcloud/index.php/s/Sv1b7krAUqmF8QQ```, +making URLs shorter and thus prettier. + +``mod_env`` and ``mod_rewrite`` must be installed on your webserver and the :file:`.htaccess` +must be writable by the HTTP user. Then you can set in the :file:`config.php` two variables:: + + 'overwrite.cli.url' => 'https://example.org/nextcloud', + 'htaccess.RewriteBase' => '/nextcloud', + +if your setup is available on ``https://example.org/nextcloud`` or:: + + 'overwrite.cli.url' => 'https://example.org', + 'htaccess.RewriteBase' => '/', + +if it isn't installed in a subfolder. Finally run this occ-command to update +your .htaccess file:: + + sudo -u www-data php /var/www/nextcloud/occ maintenance:update:htaccess + +After each update, these changes are automatically applied to the ``.htaccess``-file. .. _enabling_ssl_label: Enabling SSL ------------ -.. note:: You can use Nextcloud over plain HTTP, but we strongly encourage you - to use SSL/TLS to encrypt all of your server traffic, and to protect +.. note:: You can use Nextcloud over plain HTTP, but we strongly encourage you + to use SSL/TLS to encrypt all of your server traffic, and to protect user's logins and data in transit. Apache installed under Ubuntu comes already set-up with a simple @@ -293,9 +353,9 @@ the default site. Open a terminal and run:: service apache2 reload .. note:: Self-signed certificates have their drawbacks - especially when you - plan to make your Nextcloud server publicly accessible. You might + plan to make your Nextcloud server publicly accessible. You might want to consider getting a certificate signed by a commercial signing - authority. Check with your domain name registrar or hosting service + authority. Check with your domain name registrar or hosting service for good deals on commercial certificates. .. _installation_wizard_label: @@ -305,35 +365,25 @@ Installation Wizard After restarting Apache you must complete your installation by running either the graphical Installation Wizard, or on the command line with the ``occ`` -command. To enable this, temporarily change the ownership on your Nextcloud -directories to your HTTP user (see :ref:`strong_perms_label` to learn how to -find your HTTP user):: +command. To enable this, change the ownership on your Nextcloud directories to +your HTTP user: chown -R www-data:www-data /var/www/nextcloud/ -.. note:: Admins of SELinux-enabled distributions may need to write new SELinux - rules to complete their Nextcloud installation; see - :ref:`selinux_tips_label`. +.. note:: Admins of SELinux-enabled distributions may need to write new SELinux + rules to complete their Nextcloud installation; see + :ref:`selinux_tips_label`. -To use ``occ`` see :doc:`command_line_installation`. +To use ``occ`` see :doc:`command_line_installation`. To use the graphical Installation Wizard see :doc:`installation_wizard`. -Setting Strong Directory Permissions ------------------------------------- - -After completing installation, you must immediately set the directory -permissions in your Nextcloud installation as strictly as possible for stronger -security. Please refer to :ref:`strong_perms_label`. - -Now your Nextcloud server is ready to use. - .. _selinux_tips_label: SELinux Configuration Tips -------------------------- -See :doc:`selinux_configuration` for a suggested configuration for +See :doc:`selinux_configuration` for a suggested configuration for SELinux-enabled distributions such as Fedora and CentOS. .. _php_ini_tips_label: @@ -341,7 +391,7 @@ SELinux-enabled distributions such as Fedora and CentOS. php.ini Configuration Notes --------------------------- -Keep in mind that changes to ``php.ini`` may have to be configured on more than one +Keep in mind that changes to ``php.ini`` may have to be configured on more than one ini file. This can be the case, for example, for the ``date.timezone`` setting. **php.ini - used by the Web server:** @@ -365,68 +415,68 @@ php-fpm Configuration Notes **Security: Use at least PHP >= 5.6.6** -Due to `a bug with security implications `_ +Due to `a bug with security implications `_ in older PHP releases with the handling of XML data you are highly encouraged to run at least PHP 5.6.6 when in a threaded environment. **System environment variables** -When you are using ``php-fpm``, system environment variables like -PATH, TMP or others are not automatically populated in the same way as -when using ``php-cli``. A PHP call like ``getenv('PATH');`` can therefore -return an empty result. So you may need to manually configure environment -variables in the appropropriate ``php-fpm`` ini/config file. +When you are using ``php-fpm``, system environment variables like +PATH, TMP or others are not automatically populated in the same way as +when using ``php-cli``. A PHP call like ``getenv('PATH');`` can therefore +return an empty result. So you may need to manually configure environment +variables in the appropropriate ``php-fpm`` ini/config file. Here are some example root paths for these ini/config files: +--------------------+-----------------------+ | Ubuntu/Mint | CentOS/Red Hat/Fedora | -+--------------------+-----------------------+ ++--------------------+-----------------------+ | ``/etc/php5/fpm/`` | ``/etc/php-fpm.d/`` | -+--------------------+-----------------------+ ++--------------------+-----------------------+ -In both examples, the ini/config file is called ``www.conf``, and depending on +In both examples, the ini/config file is called ``www.conf``, and depending on the distro version or customizations you have made, it may be in a subdirectory. -Usually, you will find some or all of the environment variables +Usually, you will find some or all of the environment variables already in the file, but commented out like this:: - ;env[HOSTNAME] = $HOSTNAME - ;env[PATH] = /usr/local/bin:/usr/bin:/bin - ;env[TMP] = /tmp - ;env[TMPDIR] = /tmp - ;env[TEMP] = /tmp + ;env[HOSTNAME] = $HOSTNAME + ;env[PATH] = /usr/local/bin:/usr/bin:/bin + ;env[TMP] = /tmp + ;env[TMPDIR] = /tmp + ;env[TEMP] = /tmp -Uncomment the appropriate existing entries. Then run ``printenv PATH`` to +Uncomment the appropriate existing entries. Then run ``printenv PATH`` to confirm your paths, for example:: $ printenv PATH /home/user/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin: /sbin:/bin:/ -If any of your system environment variables are not present in the file then +If any of your system environment variables are not present in the file then you must add them. When you are using shared hosting or a control panel to manage your `Nextcloud VM -`_ or server, the configuration files are almost certain to be located -somewhere else, for security and flexibility reasons, so check your -documentation for the correct locations. +`_ or server, the configuration files are almost +certain to be located somewhere else, for security and flexibility reasons, so +check your documentation for the correct locations. -Please keep in mind that it is possible to create different settings for -``php-cli`` and ``php-fpm``, and for different domains and Web sites. +Please keep in mind that it is possible to create different settings for +``php-cli`` and ``php-fpm``, and for different domains and Web sites. The best way to check your settings is with :ref:`label-phpinfo`. **Maximum upload size** -If you want to increase the maximum upload size, you will also have to modify -your ``php-fpm`` configuration and increase the ``upload_max_filesize`` and -``post_max_size`` values. You will need to restart ``php5-fpm`` and your HTTP +If you want to increase the maximum upload size, you will also have to modify +your ``php-fpm`` configuration and increase the ``upload_max_filesize`` and +``post_max_size`` values. You will need to restart ``php5-fpm`` and your HTTP server in order for these changes to be applied. **.htaccess notes for Apache** -Nextcloud comes with its own ``nextcloud/.htaccess`` file. Because ``php-fpm`` -can't read PHP settings in ``.htaccess`` these settings and permissions must +Nextcloud comes with its own ``nextcloud/.htaccess`` file. Because ``php-fpm`` +can't read PHP settings in ``.htaccess`` these settings and permissions must be set in the ``nextcloud/.user.ini`` file. .. _other_HTTP_servers_label: @@ -434,8 +484,11 @@ be set in the ``nextcloud/.user.ini`` file. Other Web Servers ----------------- -:doc:`nginx_examples` +:doc:`nginx` `Other HTTP servers (Nextcloud) `_ + + + diff --git a/admin_manual/installation/system_requirements.rst b/admin_manual/installation/system_requirements.rst index e823cc93d..43f546e09 100644 --- a/admin_manual/installation/system_requirements.rst +++ b/admin_manual/installation/system_requirements.rst @@ -60,4 +60,4 @@ Additionally the following InnoDB settings need to be set:: innodb_file_format=barracuda innodb_file_per_table=true -See :doc:`../maintenance/mysql_4byte_support` for more information. +See :doc:`../configuration_database/mysql_4byte_support` for more information. diff --git a/admin_manual/issues/code_signing.rst b/admin_manual/issues/code_signing.rst index 30fd02e0b..351336667 100644 --- a/admin_manual/issues/code_signing.rst +++ b/admin_manual/issues/code_signing.rst @@ -46,8 +46,7 @@ version branch in version.php to something else than "stable". Is Code Signing Mandatory For Apps? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Code signing is optional for all third-party applications. Applications -with a tag of "Official" on apps.owncloud.com require code signing. +Code signing is required for all applications on apps.nextcloud.com. .. _code_signing_fix_warning_label: @@ -167,9 +166,9 @@ In above error output it can be seen that: 2. In the Nextcloud core the unrequired extra file "/test.php" has been found. 3. It was not possible to verify the signature of the calendar application. -The solution is to upload the correct "index.php" and "version.php" files, and -delete the "test.php" file. For the calendar exception contact the developer of -the application. For other means on how to receive support please take a look at +The solution is to upload the correct "index.php" and "version.php" files, and +delete the "test.php" file. For the calendar exception contact the developer of +the application. For other means on how to receive support please take a look at https://nextcloud.com/support/. After fixing these problems verify by clicking "Rescan…". diff --git a/admin_manual/issues/general_troubleshooting.rst b/admin_manual/issues/general_troubleshooting.rst index 9802bf6eb..086ae145c 100644 --- a/admin_manual/issues/general_troubleshooting.rst +++ b/admin_manual/issues/general_troubleshooting.rst @@ -37,7 +37,7 @@ configuration report with the :ref:`occ config command .. _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 + https://docs.nextcloud.org/server/12/developer_manual/bugtracker/index.html .. TODO ON RELEASE: Update version number above on release General Troubleshooting @@ -261,8 +261,8 @@ and if running in a subfolder like ``nextcloud``: For the first case the :file:`.htaccess` file shipped with Nextcloud should do this work for your when running Apache. You only need to make sure that your -Web server is using this file. When running NGINX please refer to -:doc:`../installation/nginx_examples`. +Web server is using this file. When running Nginx please refer to +:doc:`../installation/nginx`. If your Nextcloud instance is installed in a subfolder called ``nextcloud`` and diff --git a/admin_manual/maintenance/backup.rst b/admin_manual/maintenance/backup.rst index 8e2236e73..bbd5dcfb2 100644 --- a/admin_manual/maintenance/backup.rst +++ b/admin_manual/maintenance/backup.rst @@ -1,6 +1,6 @@ -==================== -Backing up Nextcloud -==================== +====== +Backup +====== To backup an Nextcloud installation there are four main things you need to retain: @@ -28,7 +28,7 @@ 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 ^^^^^^ diff --git a/admin_manual/maintenance/enable_maintenance.rst b/admin_manual/maintenance/enable_maintenance.rst deleted file mode 100644 index 84cb0a604..000000000 --- a/admin_manual/maintenance/enable_maintenance.rst +++ /dev/null @@ -1,27 +0,0 @@ -============================== -Maintenance Mode Configuration -============================== - -You must put your Nextcloud server into maintenance mode before performing -upgrades, and for performing troubleshooting and maintenance. Please -see :doc:`../configuration_server/occ_command` to learn how to put your server into -the various maintenance modes (``maintenance:mode, maintenance:singleuser``, -and ``maintenance:repair``) with the ``occ`` command. - -``maintenance:mode`` locks the sessions of logged-in users and prevents new -logins. This is the mode to use for upgrades. You must run ``occ`` as the HTTP user, -like this example on Ubuntu Linux:: - - $ sudo -u www-data php occ maintenance:mode --on - -You may also put your -server into this mode by editing :file:`config/config.php`. Change -``"maintenance" => false`` to ``"maintenance" => true``: - -:: - - true, - -Then change it back to ``false`` when you are finished. diff --git a/admin_manual/maintenance/images/updater-1-update-available.png b/admin_manual/maintenance/images/updater-1-update-available.png new file mode 100644 index 000000000..1596f9936 Binary files /dev/null and b/admin_manual/maintenance/images/updater-1-update-available.png differ diff --git a/admin_manual/maintenance/images/updater-2-open-updater.png b/admin_manual/maintenance/images/updater-2-open-updater.png new file mode 100644 index 000000000..8fd469901 Binary files /dev/null and b/admin_manual/maintenance/images/updater-2-open-updater.png differ diff --git a/admin_manual/maintenance/images/updater-3-running-step.png b/admin_manual/maintenance/images/updater-3-running-step.png new file mode 100644 index 000000000..2cfbedf5c Binary files /dev/null and b/admin_manual/maintenance/images/updater-3-running-step.png differ diff --git a/admin_manual/maintenance/images/updater-4-failed-step.png b/admin_manual/maintenance/images/updater-4-failed-step.png new file mode 100644 index 000000000..b3bb5c7f9 Binary files /dev/null and b/admin_manual/maintenance/images/updater-4-failed-step.png differ diff --git a/admin_manual/maintenance/images/updater-5-continue-update.png b/admin_manual/maintenance/images/updater-5-continue-update.png new file mode 100644 index 000000000..781449fe0 Binary files /dev/null and b/admin_manual/maintenance/images/updater-5-continue-update.png differ diff --git a/admin_manual/maintenance/images/updater-6-maintenance-mode.png b/admin_manual/maintenance/images/updater-6-maintenance-mode.png new file mode 100644 index 000000000..39f7eec29 Binary files /dev/null and b/admin_manual/maintenance/images/updater-6-maintenance-mode.png differ diff --git a/admin_manual/maintenance/images/updater-7-disable-maintenance.png b/admin_manual/maintenance/images/updater-7-disable-maintenance.png new file mode 100644 index 000000000..91b5a8df7 Binary files /dev/null and b/admin_manual/maintenance/images/updater-7-disable-maintenance.png differ diff --git a/admin_manual/maintenance/images/updater-8-keep-maintenance.png b/admin_manual/maintenance/images/updater-8-keep-maintenance.png new file mode 100644 index 000000000..6bb2eaa91 Binary files /dev/null and b/admin_manual/maintenance/images/updater-8-keep-maintenance.png differ diff --git a/admin_manual/maintenance/images/updater-9-upgrade-page.png b/admin_manual/maintenance/images/updater-9-upgrade-page.png new file mode 100644 index 000000000..07ebbc684 Binary files /dev/null and b/admin_manual/maintenance/images/updater-9-upgrade-page.png differ diff --git a/admin_manual/maintenance/images/updater-cli-2-start-updater.png b/admin_manual/maintenance/images/updater-cli-2-start-updater.png new file mode 100644 index 000000000..4cf42aee7 Binary files /dev/null and b/admin_manual/maintenance/images/updater-cli-2-start-updater.png differ diff --git a/admin_manual/maintenance/images/updater-cli-3-running-step.png b/admin_manual/maintenance/images/updater-cli-3-running-step.png new file mode 100644 index 000000000..e76f82293 Binary files /dev/null and b/admin_manual/maintenance/images/updater-cli-3-running-step.png differ diff --git a/admin_manual/maintenance/images/updater-cli-4-failed-step.png b/admin_manual/maintenance/images/updater-cli-4-failed-step.png new file mode 100644 index 000000000..722e27294 Binary files /dev/null and b/admin_manual/maintenance/images/updater-cli-4-failed-step.png differ diff --git a/admin_manual/maintenance/images/updater-cli-5-continue-update.png b/admin_manual/maintenance/images/updater-cli-5-continue-update.png new file mode 100644 index 000000000..a8821981d Binary files /dev/null and b/admin_manual/maintenance/images/updater-cli-5-continue-update.png differ diff --git a/admin_manual/maintenance/images/updater-cli-6-run-command.png b/admin_manual/maintenance/images/updater-cli-6-run-command.png new file mode 100644 index 000000000..4b5ea7157 Binary files /dev/null and b/admin_manual/maintenance/images/updater-cli-6-run-command.png differ diff --git a/admin_manual/maintenance/images/updater-cli-7-maintenance.png b/admin_manual/maintenance/images/updater-cli-7-maintenance.png new file mode 100644 index 000000000..a71c7613b Binary files /dev/null and b/admin_manual/maintenance/images/updater-cli-7-maintenance.png differ diff --git a/admin_manual/maintenance/images/updater-cli-8-no-interaction.png b/admin_manual/maintenance/images/updater-cli-8-no-interaction.png new file mode 100644 index 000000000..878759208 Binary files /dev/null and b/admin_manual/maintenance/images/updater-cli-8-no-interaction.png differ diff --git a/admin_manual/maintenance/index.rst b/admin_manual/maintenance/index.rst index 0927fe94f..ac018dc68 100644 --- a/admin_manual/maintenance/index.rst +++ b/admin_manual/maintenance/index.rst @@ -5,12 +5,11 @@ Maintenance .. toctree:: :maxdepth: 2 - enable_maintenance backup + restore upgrade - package_upgrade update manual_upgrade - restore + package_upgrade migrating - mysql_4byte_support + migrating_owncloud diff --git a/admin_manual/maintenance/manual_upgrade.rst b/admin_manual/maintenance/manual_upgrade.rst index 89bbca5cc..9b0c8c436 100644 --- a/admin_manual/maintenance/manual_upgrade.rst +++ b/admin_manual/maintenance/manual_upgrade.rst @@ -1,20 +1,9 @@ -======================== -Manual Nextcloud Upgrade -======================== +================ +Upgrade Manually +================ Always start by making a fresh backup and disabling all 3rd party apps. -Put your server in maintenance mode. This prevents new logins, locks the -sessions of logged-in users, and displays a status screen so users know what is -happening. There are two ways to do this, and the preferred method is to use the -:doc:`occ command <../configuration_server/occ_command>`, which you must run as -your HTTP user. This example is for Ubuntu Linux:: - - sudo -u www-data php occ maintenance:mode --on - -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`, for restore information see :doc:`restore`) 2. Download and unpack the latest Nextcloud Server release (Archive file) from @@ -63,17 +52,12 @@ The other way is by entering your ``config.php`` file and changing 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. - -Assuming your upgrade succeeded, disable the maintenance mode:: - - sudo -u www-data php occ maintenance:mode --off + message, or an error message that will tell where it went wrong. Login and take a look at the bottom of your Admin page to verify the version number. Check your other settings to make sure they're correct. Go to the Apps page and review the core apps to make sure the right -ones are enabled. Re-enable your third-party apps. Then apply strong -permissions to your Nextcloud directories (:ref:`strong_perms_label`). +ones are enabled. Re-enable your third-party apps. Previous Nextcloud Releases --------------------------- @@ -106,9 +90,9 @@ help:: See `the nextcloud.com support page `_ for further resources. -Sometimes, Nextcloud can get *stuck in a upgrade*. This is usually due to the -process taking too long and encountering a PHP time-out. Stop the upgrade -process this way:: +Sometimes, Nextcloud can get *stuck in a upgrade* if the web based upgrade +process is used. This is usually due to the process taking too long and +encountering a PHP time-out. Stop the upgrade process this way:: sudo -u www-data php occ maintenance:mode --off diff --git a/admin_manual/maintenance/migrating_owncloud.rst b/admin_manual/maintenance/migrating_owncloud.rst new file mode 100644 index 000000000..2cabce51f --- /dev/null +++ b/admin_manual/maintenance/migrating_owncloud.rst @@ -0,0 +1,33 @@ +======================= +Migrating from ownCloud +======================= + + +.. note:: Especially when migrating from ownCloud to Nextcloud you should + create a backup of the config, database and the data directory, + in case something goes wrong. + +Currently migrating from ownCloud is like performing a manual update. +So it is quite easy, to migrate from one ownCloud version to at least one Nextcloud version. +However this does only work with versions that are close enough database and code-wise. +See the table below for a version map, where migrating is easily possible: + ++-----------------+-----------------+ +| ownCloud | Nextcloud | ++=================+=================+ +| 10.0.1 or later | 12.0.1 or later | ++-----------------+-----------------+ +| 10.0.0 | 12.0.0 | ++-----------------+-----------------+ +| 9.1.x | 10.0.x | ++-----------------+-----------------+ +| 9.0.x | 10.0.x | ++-----------------+-----------------+ +| 9.0.x | 9.0.x | ++-----------------+-----------------+ + +After downloading the correct version of Nextcloud from our +`older releases page `_, +proceed like described in the :doc:`manual_upgrade` manual. + +Afterwards you can use the Nextcloud updater to update your instance to the newest version. diff --git a/admin_manual/maintenance/package_upgrade.rst b/admin_manual/maintenance/package_upgrade.rst index 2b0b1a0ce..54c4b575f 100644 --- a/admin_manual/maintenance/package_upgrade.rst +++ b/admin_manual/maintenance/package_upgrade.rst @@ -1,6 +1,6 @@ -=============================== -Upgrade Nextcloud From Packages -=============================== +==================== +Upgrade via Packages +==================== Upgrade Quickstart @@ -48,8 +48,6 @@ using Snappy Base 16.04 as it's currently unreleased. * Make a :doc:`fresh backup `. * Upgrade your Nextcloud snap: sudo snap refresh nextcloud * Run :ref:`occ upgrade `. -* :ref:`Apply strong permissions ` to your - Nextcloud directories. * Take your Nextcloud server out of :ref:`maintenance mode `. * Re-enable third-party apps. @@ -79,14 +77,6 @@ This example is for CentOS/RHEL/Fedora:: sudo -u apache php occ upgrade -Setting Strong Directory Permissions ------------------------------------- - -After upgrading, verify that your Nextcloud directory permissions are set -according to :ref:`strong_perms_label`. - -If the upgrade fails, then you must try a manual upgrade. - .. _skipped_release_upgrade_label: diff --git a/admin_manual/maintenance/restore.rst b/admin_manual/maintenance/restore.rst index 6579af943..5906830da 100644 --- a/admin_manual/maintenance/restore.rst +++ b/admin_manual/maintenance/restore.rst @@ -1,6 +1,6 @@ -=================== -Restoring Nextcloud -=================== +================ +Restoring Backup +================ To restore a Nextcloud installation there are four main things you need to restore: @@ -16,6 +16,9 @@ restore: When you have completed your restoration, see the ``Setting Strong Directory Permissions`` section of :doc:`../installation/installation_wizard`. +Also make sure to run the :ref:`maintenance:data-fingerprint ` command +afterwards, to ensure your sync clients can recover from the restored backup. + Restore Folders --------------- diff --git a/admin_manual/maintenance/update.rst b/admin_manual/maintenance/update.rst index e35c75b4a..398bcf4bc 100644 --- a/admin_manual/maintenance/update.rst +++ b/admin_manual/maintenance/update.rst @@ -1,177 +1,227 @@ -========================================== -Upgrading Nextcloud with the Nextcloud App -========================================== +============================ +Upgrade via build-in Updater +============================ -The Updater app automates many of the steps of upgrading an Nextcloud -installation. It is useful for installations that do not have root access, -such as shared hosting, for installations with a smaller number of users -and data, and it automates updating +The build-in updater automates many of the steps of upgrading an Nextcloud +installation. It is useful for installations that do not have root access, +such as shared hosting, for installations with a smaller number of users +and data, and it automates updating :doc:`manual installations <../installation/source_installation>`. -The Updater app has :ref:`command-line options `. - - **Downgrading** is not supported and risks corrupting your data! If you want - to revert to an older Nextcloud version, install it from scratch and then - restore your data from backup. Before doing this, file a support ticket (if - you have paid support) or ask for help in the Nextcloud forums to see if your +.. warning:: + **Downgrading** is not supported and risks corrupting your data! If you want + to revert to an older Nextcloud version, install it from scratch and then + restore your data from backup. Before doing this, file a support ticket if + you have paid support or ask for help in the Nextcloud forums to see if your issue can be resolved without downgrading. -You should maintain regular backups (see :doc:`backup`), and make a backup -before every update. The Updater app does not backup your database or data +You should maintain regular backups (see :doc:`backup`), and make a backup +before every update. The build-in updater does not backup your database or data directory. -The Updater app performs these operations: +What does the Updater do? +------------------------- -* Creates an ``updater_backup`` directory under your Nextcloud data directory -* Downloads and extracts updated package content into the - ``updater_backup/packageVersion`` directory -* Makes a copy of your current Nextcloud instance, except for your data - directory, to ``updater_backup/currentVersion-randomstring`` -* Moves all directories except ``data``, ``config`` and ``themes`` from the - current instance to ``updater_backup/tmp`` -* Moves all directories from ``updater_backup/packageVersion`` to the current - version -* Copies your old ``config.php`` to the new ``config/`` directory +.. note:: + The updater itself only replaces the existing files with the ones from the + version it updates to. The migration steps needs to be executed afterwards. + The command line mode provides a way to do this right after the code was + successfully replaced. -Using the Updater app to update your Nextcloud installation is just a few +The build-in updater performs these operations: + +* **Check for expected files:** checks if only the expected files of a + Nextcloud installation are present, because it turned out that some files + that were left in the Nextcloud directory caused side effects that risked + the update procedure. +* **Check for write permissions:** checks if all files that need to be + writable during the update procedure are actually writable. +* **Enable maintenance mode:** enables the maintenance mode so that no other + actions are executed while running the update of the code. +* **Create backup:** creates a backup of the existing code base in + ``/updater-INSTANCEID/backups/nextcloud-CURRENTVERSION/`` inside of the + data directory (this does not contain the ``/data`` directory nor the + database). +* **Downloading:** downloads the code in the version it should update to. This + is also shown in the web UI before the update is started. This archive is + downloaded to ``/updater-INSTANCEID/downloads/``. +* **Extracting:** extracts the archive to the same folder. +* **Replace entry points:** replaces all Nextcloud entry points with dummy + files so that when those files are replaced all clients still get the proper + maintenance mode response. Examples for those endpoints are ``index.php``, + ``remote.php`` or ``ocs/v1.php``. +* **Delete old files:** deletes all files except the above mentioned entry + points, the data and config dir as well as non-shipped apps and themes. (And + the updater itself of course) +* **Move new files in place:** moves the files from the extracted archive in + place. +* **Keep maintenance mode active?:** asks you if the maintenance mode should + be kept active. This allows the admin to use the web based updater but run + the actual migration steps (``occ upgrade``) on the command line. If the + maintenance mode is kept active command line access is required. To use the + web based upgrade page disable the maintenance mode and click the link to + get to the upgrade page. (This step is only available in the web based + updater.) +* **Done** the update of the code is done and you either need to go to the + linked page or to the command line to finish the upgrade by executing the + migration steps. + +Using the web based Updater +--------------------------- + +Using the build-in Updater to update your Nextcloud installation is just a few steps: -1. You should see a notification at the top of any Nextcloud page when there is - a new update available. - -2. Even though the Updater app backs up important directories, you should - always have your own current backups (See :doc:`backup` for details.) - -3. Verify that the HTTP user on your system can write to your whole Nextcloud - directory; see the :ref:`set_updating_permissions_label` section below. - -4. Navigate to your Admin page and click the **Update Center** button under - Updater. This takes you to the Updater control panel. +1. You should see a notification at the top of any Nextcloud page when there is + a new update available. Go to the admin settings page and scroll to the + section "Version". This section has a button to open the updater. This + section as well as the update notification is only available if the update + notication app is enabled in the apps management. -5. Click Update, and carefully read the messages. If there are any problems it - will tell you. The most common issue is directory permissions; your HTTP - user needs write permissions to your whole Nextcloud directory. (See - :ref:`strong_perms_label`.) Another common issue is SELinux rules - (see :ref:`selinux-config-label`.) Otherwise you will see messages - about checking your installation and making backups. +.. figure:: images/updater-1-update-available.png -6. Click Proceed, and then it performs the remaining steps, which takes a few - minutes. +2. Click the button "Open updater". -7. If your directory permissions are correct, a backup was made, and - downloading the new Nextcloud archive succeeded you will see the following - screen. Click the Start Update button to complete your update: +.. figure:: images/updater-2-open-updater.png -.. figure:: images/upgrade-2.png - :scale: 75% - :alt: Nextcloud upgrade wizard screen. +3. Verify the information that is shown and click the button "Start update" + to start the update. -.. note:: If you have a large Nextcloud installation and have shell access, - you should use the ``occ upgrade`` command, running it as your HTTP user, - instead of clicking the Start Update button, in order to avoid PHP - timeouts. - -This example is for Ubuntu Linux:: +.. figure:: images/updater-3-running-step.png - $ sudo -u www-data php occ upgrade +4. In case an error happens or the check failed the updater stops processing + and gives feedback. You can now try to solve the problem and click the + "Retry update" button. This will continue the update and re-run the failed + step. It will not re-run the previous succeeded steps. -See :doc:`../configuration_server/occ_command` to learn more. +.. figure:: images/updater-4-failed-step.png -8. It runs for a few minutes, and when it is finished displays a success - message, which disappears after a short time. +5. In case you close the updater, before it finished you can just open the + updater page again and proceed at the last succeeded step. Closing the web + page will still execute the running step but will not continue with the next + one, because this is triggered by the open updater page. -Refresh your Admin page to verify your new version number. In the Updater -section of your Admin page you can see the current status and backups. These -are backups of your old and new Nextcloud installations, and do not contain your -data files. If your update works and there are no problems you can delete the -backups from this screen. +.. figure:: images/updater-5-continue-update.png -If the update fails, then you must update manually. (See :doc:`Manually -upgrading `.) +6. Once all steps are executed the updater will ask you a final question: + "Keep maintenance mode active?". This allows you to use either the web based + upgrade page or the command line based upgrade procedure (``occ upgrade``). + Command line access is required if the maintenance mode is kept active. -.. _set_updating_permissions_label: +.. figure:: images/updater-6-maintenance-mode.png -Setting Permissions for Updating --------------------------------- - -For hardened security we highly recommend setting the permissions on your -Nextcloud directory as strictly as possible. These commands should be executed -immediately after the initial installation. Please follow the steps in -:ref:`strong_perms_label`. - -These strict permissions will prevent the Updater app from working, as it needs -your whole Nextcloud directory to be owned by the HTTP user. Run this script to -set the appropriate permissions for updating. Replace the ``ocpath`` variable -with the path to your Nextcloud directory, and replace the ``htuser`` and -``htgroup`` variables with your HTTP user and group.:: +7. Done. You now can continue either to the web based upgrade page or run + ``occ upgrade``. The two examples "Web based upgrade" and "Command line + based upgrade" shows how the screens then look like. - #!/bin/bash - # Sets permissions of the Nextcloud instance for updating - - ocpath='/var/www/nextcloud' - htuser='www-data' - htgroup='www-data' - - chown -R ${htuser}:${htgroup} ${ocpath} -You can find your HTTP user in your HTTP server configuration files. Or you can -use :ref:`label-phpinfo` (Look for the **User/Group** line). +**Web based upgrade** -* The HTTP user and group in Debian/Ubuntu is ``www-data``. -* The HTTP user and group in Fedora/CentOS is ``apache``. -* The HTTP user and group in Arch Linux is ``http``. -* The HTTP user in openSUSE is ``wwwrun``, and the HTTP group is ``www``. +This is how the web based update would continue: -After the update is completed, re-apply the strong directory permissions -immediately by running the script in :ref:`strong_perms_label`. +.. image:: images/updater-7-disable-maintenance.png -.. _updater_cli_label: +.. image:: images/updater-9-upgrade-page.png -Command Line Options --------------------- +**Command line based upgrade** -The Updater app includes command-line options to automate updates, to create -checkpoints and to roll back to older checkpoints. You must run it as your HTTP -user. This example on Ubuntu Linux displays command options:: +This is how the command line based update would continue: - sudo -u www-data php updater/application.php list - -See usage for commands, like this example for the ``upgrade:checkpoint`` -command:: +.. image:: images/updater-8-keep-maintenance.png - sudo -u www-data php updater/application.php upgrade:checkpoint -h -You can display a help summary:: - - sudo -u www-data php updater/application.php --help - -When you run it without options it runs a system check:: +.. code:: - sudo -u www-data php nextcloud/updater/application.php - Nextcloud updater 1.0 - CLI based Nextcloud server upgrades - Checking system health. - - file permissions are ok. - Current version is 9.0.0.12 - No updates found online. - Done - -Create a checkpoint:: + $ sudo -u www-data php ./occ upgrade + Nextcloud or one of the apps require upgrade - only a limited number of commands are available + You may use your browser or the occ upgrade command to do the upgrade + Set log level to debug + Updating database schema + Updated database + Updating ... + Updated to 1.1.1 + Updating ... + Updated to 17.0.0 + Updating ... + Updated to 2.5.2 + Updating ... + Updated to 1.2.0 + Updating ... + Updated to 1.3.0 + Starting code integrity check... + Finished code integrity check + Update successful + Maintenance mode is kept active + Reset log level - sudo -u www-data php updater/application.php upgrade:checkpoint --create - Created checkpoint 9.0.0.12-56d5e4e004964 +Using the command line based Updater +------------------------------------ -List checkpoints:: +The command line based updater works in the exact same way the web based +updater works. The steps and checks are the very same. - sudo -u www-data php updater/application.php upgrade:checkpoint --list - -Restore an earlier checkpoint:: +The steps are basically the same as for the web based updater: - sudo -u www-data php nextcloud/updater/application.php upgrade:checkpoint - --restore=9.0.0.12-56d5e4e004964 +1. You should see a notification at the top of any Nextcloud page when there is + a new update available. Go to the admin settings page and scroll to the + section "Version". This section has a button to open the updater. This + section as well as the update notification is only available if the update + notication app is enabled in the apps management. -Add a line like this to your crontab to automatically create daily -checkpoints:: +.. image:: images/updater-1-update-available.png + +2. Instead of clicking that button you can now invoke the command line based + updater by going into the `updater/` directory in the Nextcloud directory + and executing the `updater.phar` as the web server user. (i.e. + ``sudo -u www-data php updater.phar``) + +.. image:: images/updater-cli-2-start-updater.png + :class: terminal-image + +3. Verify the information that is shown and enter "Y" to start the update. + +.. image:: images/updater-cli-3-running-step.png + :class: terminal-image + +.. image:: images/updater-cli-4-failed-step.png + :class: terminal-image + +4. In case an error happens or the check failed the updater stops processing + and gives feedback. You can now try to solve the problem and re-run the + updater command. This will continue the update and re-run the failed step. + It will not re-run the previous succeeded steps. + +.. image:: images/updater-cli-5-continue-update.png + :class: terminal-image + +6. Once all steps are executed the updater will ask you a final question: + "Should the "occ upgrade" command be executed?". This allows you to directly + execute the command line based upgrade procedure (``occ upgrade``). If you + select "No" then it will finish with + `Please now execute "./occ upgrade" to finish the upgrade.`. + +.. image:: images/updater-cli-6-run-command.png + :class: terminal-image + +7. Once the ``occ upgrade`` is done you get asked if the maintenance mode + should be kept active. + +.. image:: images/updater-cli-7-maintenance.png + :class: terminal-image + +Batch mode for command line based updater +----------------------------------------- + +It is possible to run the command line based updater in a non-interactive mode. +The updater then doesn't ask any interactive questions. It is assumed that if +an update is available it should be installed and the ``occ upgrade`` command +is executed as well. After finishing the maintenance mode will be turned off +except an error occured during the ``occ upgrade`` or the replacement of the +code. + +To execute this, run the command with the ``--no-interaction`` option. (i.e. +``sudo -u www-data php updater.phar --no-interaction``) + +.. image:: images/updater-cli-8-no-interaction.png + :class: terminal-image - 2 15 * * * sudo -u www-data php /path/to/nextcloud/updater/application.php - upgrade:checkpoint --create > /dev/null 2>&1 - diff --git a/admin_manual/maintenance/upgrade.rst b/admin_manual/maintenance/upgrade.rst index 557132cb3..4bedd735d 100644 --- a/admin_manual/maintenance/upgrade.rst +++ b/admin_manual/maintenance/upgrade.rst @@ -1,12 +1,13 @@ -==================================== -How to Upgrade Your Nextcloud Server -==================================== +============== +How to Upgrade +============== There are three ways to upgrade your Nextcloud server: * With the :doc:`Updater App `. * :doc:`Manually upgrading ` with the Nextcloud ``.tar`` archive from our `Download page `_. +* :doc:`Upgrading ` via the snap packages. * 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 @@ -34,27 +35,21 @@ installations may take several hours to complete the upgrade. file a support ticket (if you have paid support) or ask for help in the Nextcloud forums to see if your issue can be resolved without downgrading. -.. not sure about notifications -.. Update Notifier and Updater App Are Not the Same -.. ------------------------------------------------ +Update Notifications +-------------------- -.. Nextcloud has two update tools: the Nextcloud core update notifier, and the -.. Updater app. Figure 1 shows what you see when the Updater app is enabled: -.. both -.. the core notifier and the Updater app control panel are visible on your -.. admin -.. page. +Nextcloud has an update notification app, that informs the administrator about +the availablilty of an update. Then you decide which update method to use. -.. .. figure:: images/2-updates.png -.. :alt: Both update mechanisms displayed on Admin page. +.. figure:: images/2-updates.png + :alt: Both update notifications displayed on Admin page. -.. *Figure 1: The top yellow banner is the update notifier, and the Updates -.. section is the Updater app.* + *Figure 1: The top banner is the update notification that is shown on every + page, and the Updates section can be found in the admin page* -.. The core update notifier has only one function, and that is to display a -.. notification when a new Nextcloud release is available. Then you decide which -.. upgrade method to use. When you maintain your Nextcloud server via your Linux -.. package manager you should ensure that the Updater app is disabled. +From there the web based updater can be used to fetch this new code. There is +also an CLI based updater available, that does exactly the same as the web +based updater but on the command line. Prerequisites ------------- @@ -67,3 +62,32 @@ Nextcloud release. Any apps that are not developed by Nextcloud show a 3rd party designation. **Install unsupported apps at your own risk**. Then, before the upgrade, all 3rd party apps must be disabled. After the upgrade is complete you may re-enable them. + +Maintenance mode +---------------- + +You can put your Nextcloud server into maintenance mode before performing +upgrades, or for performing troubleshooting or maintenance. Please see +:doc:`../configuration_server/occ_command` to learn how to put your server into +the maintenance mode (``maintenance:mode``) or execute repair commands +(``maintenance:repair``) with the ``occ`` command. + +The :doc:`build-in Updater ` does this for you before replacing the +existing Nextcloud code with the code of the new Nextcloud version. + +``maintenance:mode`` locks the sessions of logged-in users and prevents new +logins. This is the mode to use for upgrades. You must run ``occ`` as the HTTP +user, like this example on Ubuntu Linux:: + + $ sudo -u www-data php occ maintenance:mode --on + +You may also put your server into this mode by editing :file:`config/config.php`. +Change ``"maintenance" => false`` to ``"maintenance" => true``: + +:: + + true, + +Then change it back to ``false`` when you are finished. diff --git a/admin_manual/operations/index.rst b/admin_manual/operations/index.rst index bafaf6c76..ff662469e 100644 --- a/admin_manual/operations/index.rst +++ b/admin_manual/operations/index.rst @@ -10,5 +10,4 @@ creating a custom theme for your Nextcloud server. considerations_on_monitoring scaling_multiple_machines.rst - theming.rst diff --git a/admin_manual/operations/theming.rst b/admin_manual/operations/theming.rst deleted file mode 100644 index 86945113b..000000000 --- a/admin_manual/operations/theming.rst +++ /dev/null @@ -1,12 +0,0 @@ -================= -Theming Nextcloud -================= - -.. toctree:: - :maxdepth: 2 - :hidden: - - -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>`_. diff --git a/admin_manual/release_notes.rst b/admin_manual/release_notes.rst index 7f3829ab0..5718a8c97 100644 --- a/admin_manual/release_notes.rst +++ b/admin_manual/release_notes.rst @@ -1,9 +1,47 @@ -================================= -Nextcloud |version| Release Notes +============= +Release Notes +============= + +Changes in Nextcloud |version| +------------------------------ + +A detailed log of all changes can be found in the official `Changelog +`_. There are also all current and previous +versions linked. + +Updates to Nginx configuration +============================== + +* In the Nginx configuration the Same-Origin header was removed. This is now + handled in PHP and keeping it will result in a wrong header. Please remove + those lines in your Nginx config: + ``add_header X-Frame-Options "SAMEORIGIN";`` + See :doc:`installation/nginx` +* For improvements in serving HTTP requests the Nginx configuration now has + HTTP 2 enabled. Please update your Nginx config accordingly. See + :doc:`installation/nginx` +* The GZip configuration for Nginx was updated. See :doc:`installation/nginx` + for details. + +Common questions +---------------- + +Could not install core app bundle ================================= +The following error message is shown during the update: "Repair warning: Could +not install core app bundle: Could not download app ". -Changes in 11 -------------- +This basically means that Nextcloud could not fetch the app from the appstore +automatically. This could have multiple reasons: either you disabled the +appstore with the config.php flag or your server could not reach the app store. +The instance will work fine, but the features that are usually provided by this +app are not available. -tbd +Theming changes +=============== + +With Nextcloud 12, CSS files have been merged into one server.css so in order +to keep your theme working you should consolidate your existing css styles into +a server.css file. As for the example theme the styles.css file has been +renamed to server.css. diff --git a/developer_manual/android_library/examples.rst b/developer_manual/android_library/examples.rst index c1f4a477b..e5f767b3a 100644 --- a/developer_manual/android_library/examples.rst +++ b/developer_manual/android_library/examples.rst @@ -80,17 +80,17 @@ Code example private void startFolderCreation(String newFolderPath) { CreateRemoteFolderOperation createOperation = new CreateRemoteFolderOperation(newFolderPath, false); - createOperation.execute( mClient , this , mHandler); + createOperation.execute(mClient, this, mHandler); } @Override public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof CreateRemoteFolderOperation) { if (result.isSuccess()) { - // do your stuff here + // do your stuff here } } - … + // … } Read folder @@ -107,7 +107,7 @@ Code example .. code-block:: java private void startReadRootFolder() { - ReadRemoteFolderOperation refreshOperation = new ReadRemoteFolderOperation(FileUtils.PATH_SEPARATOR);  + ReadRemoteFolderOperation refreshOperation = new ReadRemoteFolderOperation(FileUtils.PATH_SEPARATOR); // root folder refreshOperation.execute(mClient, this, mHandler); } @@ -121,7 +121,7 @@ Code example // do your stuff here } } - … + // … } Read file @@ -148,7 +148,7 @@ Code example // do your stuff here } } - … + // … } Delete file or folder @@ -164,7 +164,7 @@ Code example private void startRemoveFile(String filePath) { RemoveRemoteFileOperation removeOperation = new RemoveRemoteFileOperation(remotePath); - removeOperation.execute( mClient , this , mHandler); + removeOperation.execute(mClient, this, mHandler); } @Override @@ -174,7 +174,7 @@ Code example // do your stuff here } } - … + // … } @@ -197,7 +197,7 @@ Code example } @Override - public void onRemoteOperationFinish( RemoteOperation operation, RemoteOperationResult result) { + public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof DownloadRemoteFileOperation) { if (result.isSuccess()) { // do your stuff here @@ -206,7 +206,7 @@ Code example } @Override - public void onTransferProgress( long progressRate, long totalTransferredSoFar, long totalToTransfer, String fileName) { + public void onTransferProgress(long progressRate, long totalTransferredSoFar, long totalToTransfer, String fileName) { mHandler.post( new Runnable() { @Override public void run() { @@ -227,8 +227,8 @@ Code example .. code-block:: java - private void startUpload (File fileToUpload, String remotePath, String mimeType) { - UploadRemoteFileOperation uploadOperation = new UploadRemoteFileOperation( fileToUpload.getAbsolutePath(), remotePath, mimeType); + private void startUpload(File fileToUpload, String remotePath, String mimeType) { + UploadRemoteFileOperation uploadOperation = new UploadRemoteFileOperation(fileToUpload.getAbsolutePath(), remotePath, mimeType); uploadOperation.addDatatransferProgressListener(this); uploadOperation.execute(mClient, this, mHandler); } @@ -244,7 +244,7 @@ Code example @Override public void onTransferProgress(long progressRate, long totalTransferredSoFar, long totalToTransfer, String fileName) { - mHandler.post( new Runnable() { + mHandler.post(new Runnable() { @Override public void run() { // do your UI updates about progress here @@ -269,24 +269,24 @@ Code example private void startFileMove(String filePath, String newFilePath, boolean overwrite) { MoveRemoteFileOperation moveOperation = new MoveRemoteFileOperation(filePath, newFilePath, overwrite); - moveOperation.execute( mClient , this , mHandler); + moveOperation.execute(mClient, this, mHandler); } @Override public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof MoveRemoteFileOperation) { if (result.isSuccess()) { - // do your stuff here + // do your stuff here } } - … + // … } Read shared items by link ------------------------- Get information about what files and folder are shared by link (the object -mClient contains the information about the server url and account) +mClient contains the information about the server URL and account). Code example ~~~~~~~~~~~~ @@ -295,16 +295,16 @@ Code example private void startAllSharesRetrieval() { GetRemoteSharesOperation getSharesOp = new GetRemoteSharesOperation(); - getSharesOp.execute( mClient , this , mHandler); + getSharesOp.execute(mClient, this, mHandler); } @Override - public void onRemoteOperationFinish( RemoteOperation operation, RemoteOperationResult result) { + public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof GetRemoteSharesOperation) { if (result.isSuccess()) { ArrayList< OCShare > shares = new ArrayList< OCShare >(); for (Object obj: result.getData()) { - shares.add(( OCShare) obj); + shares.add((OCShare) obj); } // do your stuff here } @@ -327,21 +327,21 @@ Code example private void startSharesRetrievalForFileOrFolder(String filePath, boolean getReshares) { GeteRemoteSharesForFileOperation operation = new GetRemoteSharesForFileOperation(filePath, getReshares, false); - operation.execute( mClient, this, mHandler); + operation.execute(mClient, this, mHandler); } private void startSharesRetrievalForFilesInFolder(String folderPath, boolean getReshares) { GetRemoteSharesForFileOperation operation = new GetRemoteSharesForFileOperation(folderPath, getReshares, true); - operation.execute( mClient, this, mHandler); + operation.execute(mClient, this, mHandler); } @Override - public void onRemoteOperationFinish( RemoteOperation operation, RemoteOperationResult result) { + public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof GetRemoteSharesForFileOperation) { if (result.isSuccess()) { ArrayList< OCShare > shares = new ArrayList< OCShare >(); for (Object obj: result.getData()) { - shares.add(( OCShare) obj); + shares.add((OCShare) obj); } // do your stuff here } @@ -367,7 +367,7 @@ Code example private void startCreationOfPublicShareForFile(String filePath, String password) { CreateRemoteShareOperation operation = new CreateRemoteShareOperation(filePath, ShareType.PUBLIC_LINK, "", false, password, 1); - operation.execute( mClient , this , mHandler); + operation.execute(mClient, this, mHandler); } private void startCreationOfGroupShareForFile(String filePath, String groupId) { @@ -381,10 +381,10 @@ Code example } @Override - public void onRemoteOperationFinish( RemoteOperation operation, RemoteOperationResult result) { + public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof CreateRemoteShareOperation) { if (result.isSuccess()) { - OCShare share = (OCShare) result.getData ().get(0); + OCShare share = (OCShare) result.getData().get(0); // do your stuff here } } @@ -405,14 +405,14 @@ Code example private void startShareRemoval(OCShare share) { RemoveRemoteShareOperation operation = new RemoveRemoteShareOperation((int) share.getIdRemoteShared()); - operation.execute( mClient, this, mHandler); + operation.execute(mClient, this, mHandler); } @Override - public void onRemoteOperationFinish( RemoteOperation operation, RemoteOperationResult result) { + public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof RemoveRemoteShareOperation) { if (result.isSuccess()) { - // do your stuff here + // do your stuff here } } } @@ -425,6 +425,6 @@ Tips * Paths must not be on URL Encoding * Correct path: ``https://example.com/nextcloud/remote.php/dav/PopMusic`` * Wrong path: ``https://example.com/nextcloud/remote.php/dav/Pop%20Music/`` -* There are some forbidden characters to be used in folder and files names on the server, same on the Nextcloud Android Library "\","/","<",">",":",""","|","?","*" +* There are some forbidden characters to be used in folder and file names on the server, same on the Nextcloud Android Library "\","/","<",">",":",""","|","?","*" * Upload and download actions may be cancelled thanks to the objects uploadOperation.cancel(), downloadOperation.cancel() -* Unit tests, before launching unit tests you have to enter your account information (server url, user and password) on TestActivity.java +* Unit tests, before launching unit tests you have to enter your account information (server URL, user and password) on TestActivity.java diff --git a/developer_manual/android_library/index.rst b/developer_manual/android_library/index.rst index dc96e4250..474ef61ee 100644 --- a/developer_manual/android_library/index.rst +++ b/developer_manual/android_library/index.rst @@ -13,13 +13,13 @@ library under the MIT license. Android Nextcloud Client development ------------------------------------ -If you are interested in working on the Nextcloud android client, you can find -the source code `in github `_. The +If you are interested in working on the Nextcloud Android client, you can find +the source code `in GitHub `_. The setup and process of contribution is `documented here `_. -You might want to start with doing one or two `starter issue `_ -to get into the code and note our :doc:`../general/index` +You might want to start with doing one or two `starter issues `_ +to get into the code and note our :doc:`../general/index`. Nextcloud Android Library ------------------------- @@ -27,12 +27,12 @@ Nextcloud Android Library This document will describe how to the use Nextcloud Android Library. The Nextcloud Android Library allows a developer to communicate with any Nextcloud server; among the features included are file synchronization, upload and -download of files, delete rename files and folders, etc. +download of files, delete or rename files and folders, etc. This library may be added to a project and seamlessly integrates any application with Nextcloud. -The tool needed is any IDE for Android preferred IDE at the moment is Android Studio. +The tool needed is any IDE for Android; the preferred IDE at the moment is Android Studio. .. toctree:: :maxdepth: 2 diff --git a/developer_manual/android_library/library_installation.rst b/developer_manual/android_library/library_installation.rst index 76d5fd252..e66890c2d 100644 --- a/developer_manual/android_library/library_installation.rst +++ b/developer_manual/android_library/library_installation.rst @@ -5,13 +5,11 @@ Obtaining the library --------------------- -The Nextcloud Android library may be obtained from the following Github repository: +The Nextcloud Android library may be obtained from the following GitHub repository: `https://github.com/nextcloud/android-library `_ -Once obtained, this code should be compiled. The Github repository not only contains the library, but also a sample project, sample_client -sample_client properties/android/librerias -, which will assist in learning how to use the library. +Once obtained, this code should be compiled. The GitHub repository not only contains the library, but also a sample project, *sample_client*, which will assist in learning how to use the library. Add the library to a project @@ -19,14 +17,14 @@ Add the library to a project There are different methods to add an external library to a project, we will describe two. -#. Add the library as a gradle dependency via jitpack +#. Add the library as a Gradle dependency via JitPack -#. Add the library repo to your Android project as a git submodule +#. Add the library repo to your Android project as a Git submodule -Add the library as a gradle dependency +Add the library as a Gradle dependency ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Simply open your:: @@ -37,15 +35,16 @@ and add the dependency:: compile 'com.github.nextcloud:android-library:' - refers to the exact version you would like to include in your application. This could be -SNAPSHOT for always using the latest code revision of the master branch. Alternatively you can also specifiy a version number which refers to a fixed release, e.g. 1.0.0. (compile 'com.github.nextcloud:android-library:1.0.0') + refers to the exact version you would like to include in your application. This could be -SNAPSHOT for always using the latest code revision of the master branch. Alternatively you can also specifiy a version number which refers to a fixed release, e.g. 1.0.0. (compile 'com.github.nextcloud:android-library:1.0.0'). -Add the library project to your project as a git submodule +Add the library project to your project as a Git submodule ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Basically get the code and compile it having it integrated via a git submodule +Basically get the code and compile it having it integrated via a Git submodule. Go into your own apps directory on the command line and add the Nextcloud Android library as a submodule:: + git submodule add https://github.com/nextcloud/android-library nextcloud-android-library Import/Open your app in Android Studio and you are done. All the public classes and methods of the library will be available for your own app. diff --git a/developer_manual/app/backgroundjobs.rst b/developer_manual/app/backgroundjobs.rst index 032a24296..125a8ccd0 100644 --- a/developer_manual/app/backgroundjobs.rst +++ b/developer_manual/app/backgroundjobs.rst @@ -11,7 +11,7 @@ Background/cron jobs are usually registered in the :file:`appinfo/app.php` by us query('AuthorService') ); -* The **AppName** is queried and returned from the baseclass +* The **AppName** is queried and returned from the base class * The **Request** is queried and returned from the server container * **AuthorService** is queried:: @@ -294,7 +294,6 @@ Types: * **OCP\\AppFramework\\Utility\\IControllerMethodReflector** * **OCP\\Contacts\\IManager** * **OCP\\IDateTimeZone** -* **OCP\\IDb** * **OCP\\IDBConnection** * **OCP\\Diagnostics\\IEventLogger** * **OCP\\Diagnostics\\IQueryLogger** diff --git a/developer_manual/app/controllers.rst b/developer_manual/app/controllers.rst index e9c7bcb12..b376edb72 100644 --- a/developer_manual/app/controllers.rst +++ b/developer_manual/app/controllers.rst @@ -319,7 +319,7 @@ Cookies can be set or modified directly on the response class: Responses ========= -Similar to how every controller receives a request object, every controller method has to to return a Response. This can be in the form of a Response subclass or in the form of a value that can be handled by a registered responder. +Similar to how every controller receives a request object, every controller method has to return a Response. This can be in the form of a Response subclass or in the form of a value that can be handled by a registered responder. JSON ---- @@ -342,7 +342,7 @@ Returning JSON is simple, just pass an array to a JSONResponse: } -Because returning JSON is such an common task, there's even a shorter way to do this: +Because returning JSON is such a common task, there's even a shorter way to do this: .. code-block:: php @@ -525,7 +525,7 @@ A file download can be triggered by returning a DownloadResponse: Creating custom responses ------------------------- -If no premade Response fits the needed usecase, its possible to extend the Response baseclass and custom Response. The only thing that needs to be implemented is the **render** method which returns the result as string. +If no premade Response fits the needed usecase, it is possible to extend the Response base class and custom Response. The only thing that needs to be implemented is the **render** method which returns the result as string. Creating a custom XMLResponse class could look like this: @@ -600,7 +600,7 @@ If you want to use a custom, lazily rendered response simply implement the inter Modifying the Content Security Policy ------------------------------------- -By default Nextcloud disables all resources which are not served on the same domain, forbids cross domain requests and disables inline CSS and JavaScript by setting a `Content Security Policy `_. However if an app relies on thirdparty media or other features which are forbidden by the current policy the policy can be relaxed. +By default Nextcloud disables all resources which are not served on the same domain, forbids cross domain requests and disables inline CSS and JavaScript by setting a `Content Security Policy `_. However if an app relies on third-party media or other features which are forbidden by the current policy the policy can be relaxed. .. note:: Double check your content and edge cases before you relax the policy! Also read the `documentation provided by MDN `_ @@ -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 a DataResponse 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** base class and return your data in the form of a DataResponse in the following way: .. code-block:: php @@ -729,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: @@ -745,7 +742,7 @@ Most of the time though it makes sense to also allow normal users to access the To turn off checks the following *Annotations* can be added before the controller: * **@NoAdminRequired**: Also users that are not admins can access the page -* **@NoCSRFRequired**: Don't check the CSRF token (use this wisely since you might create a security hole, to understand what it does see :doc:`../general/security`) +* **@NoCSRFRequired**: Don't check the CSRF token (use this wisely since you might create a security hole; to understand what it does see :doc:`../general/security`) * **@PublicPage**: Everyone can access the page without having to log in A controller method that turns off all checks would look like this: @@ -771,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 + + auth->isSuccessful here is just an + // example. + if(!$this->auth->isSuccessful()) { + $templateResponse->throttle(); + } + return $templateResponse; + } + } \ No newline at end of file diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index 8406bdd76..444a5321a 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -15,7 +15,7 @@ The CSS files reside in the **css/** folder and should be included in the templa // include multiple files for the same app style('myapp', array('style', 'navigation')); // adds css/style.css, css/navigation.css - // include vendor file (also allows vendor syntax) + // include vendor file (also allows array syntax) vendor_style('myapp', 'style'); // adds vendor/style.css Web Components go into the **component/** folder and can be imported like this: @@ -30,7 +30,7 @@ Web Components go into the **component/** folder and can be imported like this: component('myapp', array('tabs', 'forms')); // adds component/tabs.html, component/forms.html -.. note:: Keep in mind that Web Components are still very new and you `might need to add polyfills using Polymer `_ +.. note:: Keep in mind that Web Components are still very new and you `might need to add polyfills `_ Standard layout =============== @@ -71,7 +71,7 @@ Nextcloud provides a default CSS navigation layout. If list entries should have Folders ------- -Folders are like normal entries and are only supported for the first level. In contrast to normal entries, the links which show the title of the folder need to have the **icon-folder** css class. +Folders are like normal entries and are only supported for the first level. In contrast to normal entries, the links which show the title of the folder need to have the **icon-folder** CSS class. If the folder should be collapsible, the **collapsible** class and a button with the class **collapse** are needed. After adding the collapsible class the folder's child entries can be toggled by adding the **open** class to the list element: @@ -116,7 +116,7 @@ Menus .. versionadded:: 8 -To add actions that affect the current list element you can add a menu for second and/or first level elements by adding the button and menu inside the corresponding **li** element and adding the **with-menu** css class: +To add actions that affect the current list element you can add a menu for second and/or first level elements by adding the button and menu inside the corresponding **li** element and adding the **with-menu** CSS class: .. code-block:: html @@ -132,10 +132,20 @@ To add actions that affect the current list element you can add a menu for secon -
+
@@ -143,7 +153,7 @@ To add actions that affect the current list element you can add a menu for secon
-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. +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-overflow of the entry's title. The count should be limitted to 999 and turn to 999+ if any higher number is given. If AngularJS is used the following filter can be used to get the correct behaviour: @@ -264,7 +274,7 @@ If you want to undo a performed action on a navigation entry such as deletion, y Settings Area ============= -To create a settings area create a div with the id **app-settings** inside the **app-navgiation** div: +To create a settings area create a div with the id **app-settings** inside the **app-navigation** div: .. code-block:: html @@ -278,7 +288,7 @@ To create a settings area create a div with the id **app-settings** inside the *
+ >t('Settings'));?>
diff --git a/developer_manual/app/database.rst b/developer_manual/app/database.rst index 5be71c522..5875e4dba 100644 --- a/developer_manual/app/database.rst +++ b/developer_manual/app/database.rst @@ -48,7 +48,7 @@ The aforementioned example is the most basic way to write a simple database quer To generalize and simplify the problem, split code into resources and create an **Entity** and a **Mapper** class for it. The mapper class provides a way to run SQL queries and maps the result onto the related entities. -To create a mapper, inherit from the mapper baseclass and call the parent constructor with the following parameters: +To create a mapper, inherit from the mapper base class and call the parent constructor with the following parameters: * Database connection * Table name @@ -100,7 +100,7 @@ To create a mapper, inherit from the mapper baseclass and call the parent constr } -.. note:: The cursor is closed automatically for all **INSERT**, **DELETE**, **UPDATE** queries and when calling the methods **findOneQuery**, **findEntities**, **findEntity**, **delete**, **insert** and **update**. For custom calls using execute you should always close the cursor after you are done with the fetching to prevent database lock problems on SqLite +.. note:: The cursor is closed automatically for all **INSERT**, **DELETE**, **UPDATE** queries and when calling the methods **findOneQuery**, **findEntities**, **findEntity**, **delete**, **insert** and **update**. For custom calls using execute you should always close the cursor after you are done with the fetching to prevent database lock problems on SQLite Every mapper also implements default methods for deleting and updating an entity based on its id:: @@ -114,7 +114,7 @@ or:: Entities ======== -Entities are data objects that carry all the table's information for one row. Every Entity has an **id** field by default that is set to the integer type. Table rows are mapped from lower case and underscore separated names to pascal case attributes: +Entities are data objects that carry all the table's information for one row. Every Entity has an **id** field by default that is set to the integer type. Table rows are mapped from lower case and underscore separated names to *lowerCamelCase* attributes: * **Table column name**: phone_number * **Property name**: phoneNumber @@ -141,7 +141,7 @@ Entities are data objects that carry all the table's information for one row. Ev Types ----- -The following properties should be annotated by types, to not only assure that the types are converted correctly for storing them in the database (e.g. PHP casts false to the empty string which fails on postgres) but also for casting them when they are retrieved from the database. +The following properties should be annotated by types, to not only assure that the types are converted correctly for storing them in the database (e.g. PHP casts false to the empty string which fails on PostgreSQL) but also for casting them when they are retrieved from the database. The following types can be added for a field: @@ -204,7 +204,7 @@ mapping, simply override the **columnToProperty** and **propertyToColumn** metho } public function propertyToColumn($property) { - if ($column === 'phoneNumber') { + if ($property === 'phoneNumber') { return 'phonenumber'; } else { return parent::propertyToColumn($property); @@ -216,7 +216,7 @@ mapping, simply override the **columnToProperty** and **propertyToColumn** metho Slugs ----- -Slugs are used to identify resources in the URL by a string rather than integer id. Since the URL allows only certain values, the entity baseclass provides a slugify method for it: +Slugs are used to identify resources in the URL by a string rather than integer id. Since the URL allows only certain values, the entity base class provides a slugify method for it: .. code-block:: php diff --git a/developer_manual/app/hooks.rst b/developer_manual/app/hooks.rst index 5191b4713..5369d2e1f 100644 --- a/developer_manual/app/hooks.rst +++ b/developer_manual/app/hooks.rst @@ -14,7 +14,7 @@ Hooks are used to execute code before or after an event has occurred. This is fo $app = new Application(); $app->getContainer()->query('UserHooks')->register(); -The hook logic should be in a separate class that is being registered in the :doc:`container` +The hook logic should be in a separate class that is being registered in the :doc:`container`: .. code-block:: php @@ -108,7 +108,7 @@ Hooks available in scope **\\OC\\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 diff --git a/developer_manual/app/index.rst b/developer_manual/app/index.rst index b132a166d..f7301d3ca 100644 --- a/developer_manual/app/index.rst +++ b/developer_manual/app/index.rst @@ -35,6 +35,7 @@ backgroundjobs settings logging + repair testing publishing code_signing @@ -47,7 +48,7 @@ App Development Intro ===== -Before you start, please check if there already is a similar app in the `App Store `_ or the `GitHub organisation `_ that you could contribute to. Also, feel free to communicate your idea and plans in the `forum `_ so other contributors might join in. +Before you start, please check if there already is a similar app in the `App Store `_ or the `GitHub organisation `_ that you could contribute to. Also, feel free to communicate your idea and plans in the `forum `_ so other contributors might join in. Then, please make sure you have set up a development environment: @@ -149,6 +150,12 @@ Log to the :file:`data/nextcloud.log`: * :doc:`logging` +Repair steps +------------ +Repair steps can be used to run code at various stages in app installation, uninstallation, migration ... + +* :doc:`repair` + Testing ------- Write automated tests to ensure stability and ease maintenance: diff --git a/developer_manual/app/info.rst b/developer_manual/app/info.rst index 88946275c..8bcecf2ea 100644 --- a/developer_manual/app/info.rst +++ b/developer_manual/app/info.rst @@ -143,10 +143,17 @@ category -------- Category on the app store. Can be one of the following: +* auth +* customization +* files +* games +* integration +* monitoring * multimedia -* productivity -* game -* tool +* office +* organization +* social +* tools ocsid ----- @@ -175,7 +182,7 @@ specified. Valid values for the 'os' attribute are as returned by the PHP functi 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 `_. -The explicit version of an extension is read from `phpversion `_ - with some exception as to be read up in the `code base `_ +The explicit version of an extension is read from `phpversion `_ - with some exception as to be read up in the `code base `_. os == @@ -185,7 +192,7 @@ owncloud ======== **Required**: Defines minimum and maximum versions of the Nextcloud core. In case undefined the values will be taken from the tag `requiremin`_. -.. note:: Currently this tag is also used to check for the nextcloud version number. +.. note:: Currently this tag is also used to check for the Nextcloud version number. Thereby the following "translation" is made: * ownCloud 9.0 matches Nextcloud 9 @@ -211,7 +218,7 @@ In case the app has its own admin related settings, it needs to implement the \O Deprecated ---------- -The following sections are just listed for reference and should not be used because +The following sections are just listed for reference and should not be used; they are deprecated and often not evaluated anymore (i.e., they are ignored). requiremin ========== diff --git a/developer_manual/app/init.rst b/developer_manual/app/init.rst index e414aab5e..80cbec9f2 100644 --- a/developer_manual/app/init.rst +++ b/developer_manual/app/init.rst @@ -13,7 +13,7 @@ The :file:`appinfo/app.php` is the first file that is loaded and executed in Nex \OC::$server->getNavigationManager()->add(function () { $urlGenerator = \OC::$server->getURLGenerator(); return [ - // the string under which your app will be referenced in nextcloud + // the string under which your app will be referenced in Nextcloud 'id' => 'myapp', // sorting weight for the navigation. The higher the number, the higher diff --git a/developer_manual/app/l10n.rst b/developer_manual/app/l10n.rst index 23e9be550..3fccb8f05 100644 --- a/developer_manual/app/l10n.rst +++ b/developer_manual/app/l10n.rst @@ -4,11 +4,11 @@ Translation .. sectionauthor:: Bernhard Posselt -Nextcloud's translation system is powered by `Transifex `_. To start translating sign up and enter a group. If your community app should be added to Transifex contact one of the translation team `in the forums `_ to set it up for you. +Nextcloud's translation system is powered by `Transifex `_. To start translating sign up and enter a group. If your community app should be added to Transifex contact one of the translation teams `in the forums `_ to set it up for you. PHP === -Should it ever be needed to use localized strings on the server-side, simply inject the L10N service from the ServerContainer into the needed constructor +Should it ever be needed to use localized strings on the server-side, simply inject the L10N service from the ServerContainer into the needed constructor: .. code-block:: php @@ -103,7 +103,7 @@ There is a global function **t()** available for translating strings. The first t('myapp', 'Hello World!'); -For advanced usage, refer to the source code **core/js/l10n.js**, **t()** is bind to **OC.L10N.translate()**. +For advanced usage, refer to the source code **core/js/l10n.js**; **t()** is bind to **OC.L10N.translate()**. Hints ===== diff --git a/developer_manual/app/middleware.rst b/developer_manual/app/middleware.rst index 1a73053eb..102e68bf5 100644 --- a/developer_manual/app/middleware.rst +++ b/developer_manual/app/middleware.rst @@ -8,7 +8,7 @@ Middleware is logic that is run before and after each request and is modelled af * **beforeController**: This is executed before a controller method is being executed. This allows you to plug additional checks or logic before that method, like for instance security checks * **afterException**: This is being run when either the beforeController method or the controller method itself is throwing an exception. The middleware is asked in reverse order to handle the exception and to return a response. If the middleware can't handle the exception, it throws the exception again -* **afterController**: This is being run after a successful controllermethod call and allows the manipulation of a Response object. The middleware is run in reverse order +* **afterController**: This is being run after a successful controller method call and allows the manipulation of a Response object. The middleware is run in reverse order * **beforeOutput**: This is being run after the response object has been rendered and allows the manipulation of the outputted text. The middleware is run in reverse order To generate your own middleware, simply inherit from the Middleware class and overwrite the methods that should be used. @@ -77,7 +77,7 @@ The middleware can be registered in the :doc:`container` and added using the **r Parsing annotations =================== -Sometimes its useful to conditionally execute code before or after a controller method. This can be done by defining custom annotations. An example would be to add a custom authentication method or simply add an additional header to the response. To access the parsed annotations, inject the **ControllerMethodReflector** class: +Sometimes it is useful to conditionally execute code before or after a controller method. This can be done by defining custom annotations. An example would be to add a custom authentication method or simply add an additional header to the response. To access the parsed annotations, inject the **ControllerMethodReflector** class: .. code-block:: php diff --git a/developer_manual/app/publishing.rst b/developer_manual/app/publishing.rst index dd9b29154..1ec035047 100644 --- a/developer_manual/app/publishing.rst +++ b/developer_manual/app/publishing.rst @@ -6,7 +6,7 @@ App store publishing The Nextcloud App Store ----------------------- -The Nextcloud app store is build into Nextcloud to allow you to get your apps to users as easily and safely as possible. The app store and the process of publishing apps aims to be: +The Nextcloud app store is built into Nextcloud to allow you to get your apps to users as easily and safely as possible. The app store and the process of publishing apps aims to be: * secure * transparent @@ -14,96 +14,13 @@ The Nextcloud app store is build into Nextcloud to allow you to get your apps to * fair * easy to maintain -Apps in the store are divided in three 'levels' of trust: - -* Official -* Approved -* Experimental - -With each level come requirements and a position in the store. - -Official -^^^^^^^^ -Official apps are developed by and within the Nextcloud community and its `Github `_ repository and offer functionality central to Nextcloud. They are ready for serious use and can be considered a part of Nextcloud. - -Requirements: - -* developed in Nextcloud github repo -* minimum of 2 active maintainers and contributions from others -* security audited and design reviewed -* app is at least 6 months old and has seen regular releases -* follows app guidelines -* supports the same platforms and technologies mentioned in the release notes of the Nextcloud version this app is made for - -.. * app is signed, identity verified - -App store: - -* available in Apps page in separate category -* sorted first in all overviews, 'Official' tag -* shown as featured, on nextcloud.com etc -* major releases optionally featured on nextcloud.com -* new versions/updates approved by at least one other person - -note: -Official apps include those that are part of the release tarball. We'd like to keep the tarball minimal so most official apps are not part of the standard installation. - -Approved -^^^^^^^^ -Approved apps are developed by trusted developers and have passed a cursory security check. They are actively maintained in an open code repository and their maintainers deem them to be stable for casual to normal use. - -Requirements: - -* code is developed in an open and version-managed code repository, ideally github with git but other scm/hosting is OK. -* minimum of one active developer/maintainer -* minimum 5 ratings, average score 60/100 or better -* app is at least 3 months old -* follows app guidelines -* the developer is trusted -* app is subject to unannounced security audits -* has defined requirements and dependencies (like what browsers, databases, PHP versions and so on are supported) - -.. * app is signed, at least domain verified - -.. note:: **Developer trust**: The developer(s) is/are known in community; he/she has/have been active for a while, have met others at events and/or worked with others in various areas. -.. note:: **security audits**: in practice this means that at least some of the code of this developer has been audited; either through another app by the same developer or with an earlier version of the app. And that the attitude of the developer towards these audits has been positive. - -App store: - -* visible in app store by default -* sorted above experimental apps -* search results sorted by ratings -* developer can directly push new versions to the store -* warning shows for security/stability risks - -Experimental -^^^^^^^^^^^^ -Apps which have not been checked at all for security and/or are new, known to be unstable or under heavy development. - -Requirements: - -* no malicious intent found from this developer at any time -* 0 confirmed security problems -* less than 3 unconfirmed 'security flags' -* rating over 20/100 - -.. * app is signed but no verification has to be done - -App store: - -* show up in Apps page provided user has enabled "allow installation of experimental apps" in the settings. -* Warning about security and stability risks is shown for app -* sorted below all others. - Getting an app approved ----------------------- -If you want your app to be approved, make sure you fulfill all the requirements and then create an issue in the `app approval github repository `_ using `this template `_. A team of Nextcloud contributors will review your application. Updates to an app require re-review but, of course, an initial review takes more effort and time than the checking of an update. - -You are encouraged to help review other contributors' apps as well! Every app requires at least two independent reviews so your review of at least 2 (more is better!) other apps will ensure the process continues smoothly. Thank you for participating in this process and being a great Nextcloud Community member! +You can find documentation on getting apps in our app store `here. `_ Using the code checker ^^^^^^^^^^^^^^^^^^^^^^ -Before asking for approval, it is best to check your app code with the code checker, and fix the issues found by the code checker. +Before getting the app in the app store, it is best to check your app code with the code checker, and fix the issues found by the code checker. .. code-block:: bash @@ -124,28 +41,28 @@ These are the app guidelines an app has to comply with to have a chance to be ap Legal and security ^^^^^^^^^^^^^^^^^^ -* Apps can not use 'Nextcloud' in their name +* Apps can not use 'Nextcloud' in their name. * Irregular and unannounced security audits of all apps can and will take place. * If any indication of malicious intent or bad faith is found the developer(s) in question can count on a minimum 2 year ban from any Nextcloud infrastructure. * Malicious intent includes deliberate spying on users by leaking user data to a third party system or adding a back door (like a hard-coded user account) to Nextcloud. An unintentional security bug that gets fixed in time won't be considered bad faith. * Apps do not violate any laws; it has to comply with copyright- and trademark law. * App authors have to respond timely to security concerns and not make Nextcloud more vulnerable to attack. -.. note:: distributing malicious or illegal applications can have legal consequences including, but not limited to Nextcloud or affected users taking legal action. +.. note:: Distributing malicious or illegal applications can have legal consequences including, but not limited to Nextcloud or affected users taking legal action. Be technically sound ^^^^^^^^^^^^^^^^^^^^ -* Apps can only use the public Nextcloud API -* At time of the release of an app it can only be configured to be compatible with the latest Nextcloud release +1 -* Apps should not cause Nextcloud to break, consume excessive memory or slow Nextcloud down -* Apps should not hamper functionality of Nextcloud unless that is explicitly the goal of the app +* Apps can only use the public Nextcloud API. +* At time of the release of an app it can only be configured to be compatible with the latest Nextcloud release +1. +* Apps should not cause Nextcloud to break, consume excessive memory or slow Nextcloud down. +* Apps should not hamper functionality of Nextcloud unless that is explicitly the goal of the app. Respect the users ^^^^^^^^^^^^^^^^^ -* Apps have to follow design and `HTML/CSS layout guidelines <../app/css.html>`_ -* Apps correctly clean up after themselves on uninstall and correctly handle up- and downgrades +* Apps have to follow design and `HTML/CSS layout guidelines <../app/css.html>`_. +* Apps correctly clean up after themselves on uninstall and correctly handle up- and downgrades. * Apps clearly communicate their intended purpose and active features, including features introduced through updates. * Apps respect the users' choices and do not make unexpected changes, or limit users' ability to revert them. For example, they do not remove other apps or disable settings. * Apps must respect user privacy. IF user data is sent anywhere, this must be clearly explained and be kept to a minimum for the functioning of an app. Use proper security measures when needed. diff --git a/developer_manual/app/repair.rst b/developer_manual/app/repair.rst new file mode 100644 index 000000000..3a71965df --- /dev/null +++ b/developer_manual/app/repair.rst @@ -0,0 +1,111 @@ +============ +Repair Steps +============ + +Repair steps are methods which are executed by Nextcloud on certain +events which directly affect the app. You can use these repair steps to run +code when your app is installed, uninstalled, upgraded etc. It's called repair +steps because they are frequently used to fix things automatically. + +.. note:: Don't use the ``install.php``, ``update.php`` and ``preupdate.php`` files anymore! This method is deprecated and is known to cause issues. + + +Creating a repair step +====================== +A repair step is an implementation of the ``OCP\Migration\IRepairStep`` interface. +By convention these classes are placed in the **lib/Migration** directory. +The following repairstep will log a message when executed. + +.. code-block:: php + + logger = $logger; + } + + /** + * Returns the step's name + */ + public function getName() { + return 'A demonstration repair step!'; + } + + /** + * @param IOutput $output + */ + public function run(IOutput $output) { + $this->logger->warning("Hello world from MyRepairStep!", ["app" => "MyApp"]); + } + } + +Outputting information +~~~~~~~~~~~~~~~~~~~~~ +A repair step can generate information while running, using the +``OCP\Migration\IOutput`` parameter to the ``run`` method. +Using the ``info`` and ``warning`` methods a message can be shown in the console. +In order to show a progressbar, firstly call the ``startProgress`` method. +The maximum number of steps can be adjusted by passing it as argument to the +``startProgress`` method. After every step run the ``advance`` method. Once all steps are finished run the ``finishProgress`` +method. + +The following function will sleep for 10 seconds and show the progress: + +.. code-block:: php + + info("This step will take 10 seconds."); + $output->startProgress(10); + for ($i = 0; $i < 10; $i++) { + sleep(1); + $output->advance(1); + } + $output->finishProgress(); + } + +Register a repair-step +====================== +To register a repair-step in Nextcloud you have to define the repair-setp in the ``info.xml`` +file. The following example registers a repair-step which will be executed after installation +of the app: + +.. code-block:: xml + + + + myapp + My App + A test app + ... + + + OCA\MyApp\Migration\MyRepairStep + + + + + +Repair-step types +================= +The following repair steps are available: + +* ``install`` This repair step will be executed when installing the app. This means it is executed every time the app is enabled (using the Web interface or the CLI). +* ``uninstall`` This repair step will be executed when uninstalling the app, and when disabling the app. +* ``pre-migration`` This repair step will be executed just before the database is migrated during an update of the app. +* ``post-migration`` This repair step will be executed just after the database is migrated during an update of the app. This repair step will also be executed when running the ``occ maintenance:repair`` command +* ``live-migration`` This repair step will be scheduled to be run in the background (e.g. using cron), therefore it is unpredictable when it will run. If the job isn't required right after the update of the app and the job would take a long time this is the best choice. diff --git a/developer_manual/app/request.rst b/developer_manual/app/request.rst index 445f3932e..7753490e9 100644 --- a/developer_manual/app/request.rst +++ b/developer_manual/app/request.rst @@ -6,7 +6,7 @@ Request lifecycle A typical HTTP request consists of the following: -* **An URL**: e.g. /index.php/apps/myapp/something +* **A URL**: e.g. /index.php/apps/myapp/something * **Request Parameters**: e.g. ?something=true&name=tom * **A Method**: e.g. GET * **Request headers**: e.g. Accept: application/json @@ -15,7 +15,7 @@ The following sections will present an overview over how that request is being p Front controller ================ -In the beginning, all requests are sent to Nextcloud's :file:`index.php` which in turn executes :file:`lib/base.php`. This file inspects the HTTP headers and abstracts away differences between different Web servers and initializes the basic classes. Afterwards the basic apps are being loaded in the following order: +In the beginning, all requests are sent to Nextcloud's :file:`index.php` which in turn executes :file:`lib/base.php`. This file inspects the HTTP headers, abstracts away differences between different Web servers and initializes the basic classes. Afterwards the basic apps are being loaded in the following order: * Authentication backends * Filesystem diff --git a/developer_manual/app/routes.rst b/developer_manual/app/routes.rst index 93575fe59..28f03f2dc 100644 --- a/developer_manual/app/routes.rst +++ b/developer_manual/app/routes.rst @@ -4,7 +4,7 @@ Routing .. sectionauthor:: Bernhard Posselt -Routes map an URL and a method to a controller method. Routes are defined inside :file:`appinfo/routes.php` by passing a configuration array to the registerRoutes method. An example route would look like this: +Routes map a URL and a method to a controller method. Routes are defined inside :file:`appinfo/routes.php` by passing a configuration array to the registerRoutes method. An example route would look like this: .. code-block:: php @@ -21,7 +21,7 @@ Routes map an URL and a method to a controller method. Routes are defined inside The route array contains the following parts: -* **url**: The url that is matched after */index.php/apps/myapp* +* **url**: The URL that is matched after */index.php/apps/myapp* * **name**: The controller and the method to call; *page#index* is being mapped to *PageController->index()*, *articles_api#drop_latest* would be mapped to *ArticlesApiController->dropLatest()*. The controller that matches the page#index name would have to be registered in the following way inside :file:`appinfo/application.php`: .. code-block:: php @@ -54,9 +54,9 @@ The route array contains the following parts: } * **method** (Optional, defaults to GET): The HTTP method that should be matched, (e.g. GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH) -* **requirements** (Optional): lets you match and extract URLs that have slashes in them (see **Matching suburls**) -* **postfix** (Optional): lets you define a route id postfix. Since each route name will be transformed to a route id (**page#method** -> **myapp.page.method**) and the route id can only exist once you can use the postfix option to alter the route id creation by adding a string to the route id e.g.: **'name' => 'page#method', 'postfix' => 'test'** will yield the route id **myapp.page.methodtest**. This makes it possible to add more than one route/url for a controller method -* **defaults** (Optional): If this setting is given, a default value will be assumed for each url parameter which is not present. The default values are passed in as a key => value par array +* **requirements** (Optional): lets you match and extract URLs that have slashes in them (see :ref:`matching-suburls`) +* **postfix** (Optional): lets you define a route id postfix. Since each route name will be transformed to a route id (**page#method** -> **myapp.page.method**) and the route id can only exist once you can use the postfix option to alter the route id creation by adding a string to the route id, e.g., **'name' => 'page#method', 'postfix' => 'test'** will yield the route id **myapp.page.methodtest**. This makes it possible to add more than one route/URL for a controller method +* **defaults** (Optional): If this setting is given, a default value will be assumed for each URL parameter which is not present. The default values are passed in as a key => value par array Extracting values from the URL ============================== @@ -83,9 +83,11 @@ It is possible to extract values from the URL to allow RESTful URL design. To ex The identifier used inside the route is being passed into controller method by reflecting the method parameters. So basically if you want to get the value **{id}** in your method, you need to add **$id** to your method parameters. -Matching suburls +.. _matching-suburls: + +Matching subURLs ================ -Sometimes its needed to match more than one URL fragment. An example would be to match a request for all URLs that start with **OPTIONS /index.php/apps/myapp/api**. To do this, use the **requirements** parameter in your route which is an array containing pairs of **'key' => 'regex'**: +Sometimes it is needed to match more than one URL fragment. An example would be to match a request for all URLs that start with **OPTIONS /index.php/apps/myapp/api**. To do this, use the **requirements** parameter in your route which is an array containing pairs of **'key' => 'regex'**: .. code-block:: php @@ -106,9 +108,9 @@ Sometimes its needed to match more than one URL fragment. An example would be to } -Default values for suburl +Default values for subURL ========================== -Apart from matching requirements, a suburl may also have a default value. Say you want to support pagination (a 'page' parameter) for your **/posts** suburl that displays posts entries list. You may set a default value for the 'page' parameter, that will be used if not already set in the url. Use the **defaults** parameter in your route which is an array containing pairs of **'urlparameter' => 'defaultvalue'**: +Apart from matching requirements, a subURL may also have a default value. Say you want to support pagination (a 'page' parameter) for your **/posts** subURL that displays posts entries list. You may set a default value for the 'page' parameter, that will be used if not already set in the URL. Use the **defaults** parameter in your route which is an array containing pairs of **'urlparameter' => 'defaultvalue'**: .. code-block:: php @@ -121,7 +123,7 @@ Apart from matching requirements, a suburl may also have a default value. Say yo 'name' => 'post#index', 'url' => '/post/{page}', 'verb' => 'GET', - 'defaults' => array('page' => 1) // this allows same url as /index.php/myapp/post/1 + 'defaults' => array('page' => 1) // this allows same URL as /index.php/myapp/post/1 ), // controller/postcontroller.php @@ -181,7 +183,7 @@ can be abbreviated by using the **resources** key: Using the URLGenerator ======================== -Sometimes its useful to turn a route into a URL to make the code independent from the URL design or to generate an URL for an image in **img/**. For that specific use case, the ServerContainer provides a service that can be used in your container: +Sometimes it is useful to turn a route into a URL to make the code independent from the URL design or to generate a URL for an image in **img/**. For that specific use case, the ServerContainer provides a service that can be used in your container: .. code-block:: php @@ -216,7 +218,7 @@ Sometimes its useful to turn a route into a URL to make the code independent fro } -Inside the PageController the URL generator can now be used to generate an URL for a redirect: +Inside the PageController the URL generator can now be used to generate a URL for a redirect: .. code-block:: php diff --git a/developer_manual/app/settings.rst b/developer_manual/app/settings.rst index 96a06ed42..d91f65e9d 100644 --- a/developer_manual/app/settings.rst +++ b/developer_manual/app/settings.rst @@ -12,16 +12,16 @@ Admin For Nextcloud 10 the admin settings page got reworked. It is not a long list anymore, but divided into sections, where related settings forms are grouped. For example, in the **Sharing** section are only settings (built-in and of apps) -relate to sharing. +related to sharing. Settings Form ============= -For the settings form, three things are necessary +For the settings form, three things are necessary: 1. A class implementing ``\OCP\Settings\ISettings`` 2. A template -3. The implementing class specified in the apps`s info.xml +3. The implementing class specified in the app's info.xml Below is an example for an implementor of the ISettings interface. It is based on the survey_client solution. @@ -202,8 +202,8 @@ implementation of the **user_ldap** app. Section ======= -It is also possible, that an app registers its own section. This should be done -only, if there is not fitting corresponding section and the apps settings form +It is also possible that an app registers its own section. This should be done +only if there is not fitting corresponding section and the apps settings form takes a lot of screen estate. Otherwise, register to "additional". Basically, it works the same way as with the settings form. There are only two @@ -260,7 +260,7 @@ An example implementation of the ISection interface: } -Also the section must be registered in the apps`s info.xml. +Also the section must be registered in the app's info.xml. Personal -------- diff --git a/developer_manual/app/startapp.rst b/developer_manual/app/startapp.rst index bc73379b9..af12d1a2a 100644 --- a/developer_manual/app/startapp.rst +++ b/developer_manual/app/startapp.rst @@ -12,7 +12,7 @@ Then create a skeleton app in the `app store -All PHP classes can be tested with `PHPUnit `_, JavaScript can be tested by using `Karma `_. +All PHP classes can be tested with `PHPUnit `_, JavaScript can be tested by using `Karma `_. diff --git a/developer_manual/app/tutorial.rst b/developer_manual/app/tutorial.rst index 9f180711a..971ab407b 100644 --- a/developer_manual/app/tutorial.rst +++ b/developer_manual/app/tutorial.rst @@ -4,7 +4,7 @@ Tutorial .. sectionauthor:: Bernhard Posselt -This tutorial will outline how to create a very simple notes app. The finished app is available on `GitHub `_. +This tutorial will outline how to create a very simple notes app. The finished app is available on `GitHub `_. Setup @@ -33,7 +33,7 @@ Now open another terminal window and start the development server:: Afterwards a skeleton app can be created in the `app store `_. -Download the extracted the downloaded file and move it into your ``apps/`` directory. Afterwards the application can be enabled on the `apps page `_. +Download the compressed file that contains the generated app and extract it into your ``apps/`` directory. Afterwards the application can be enabled on the `apps page `_. The first basic app is now available at ``http://localhost:8080/index.php/apps/yourappid/`` @@ -172,7 +172,7 @@ Since the route which returns the initial HTML has been taken care of, the contr } -.. note:: The parameters are extracted from the request body and the url using the controller method's variable names. Since PHP does not support type hints for primitive types such as ints and booleans, we need to add them as annotations in the comments. In order to type cast a parameter to an int, add **@param int $parameterName** +.. note:: The parameters are extracted from the request body and the URL using the controller method's variable names. Since PHP does not support type hints for primitive types such as ints and booleans, we need to add them as annotations in the comments. In order to type cast a parameter to an int, add **@param int $parameterName** Now the controller methods need to be connected to the corresponding URLs in the **ownnotes/appinfo/routes.php** file: @@ -310,12 +310,12 @@ Entities are returned from so called :doc:`Mappers `. Let's create one
  • t('Add note')); ?>
    • {{#each notes}} -
  • +
  • {{ title }}
      diff --git a/developer_manual/app/users.rst b/developer_manual/app/users.rst index 74819b01d..94898681d 100644 --- a/developer_manual/app/users.rst +++ b/developer_manual/app/users.rst @@ -1,6 +1,6 @@ -============== -Usermanagement -============== +=============== +User Management +=============== .. sectionauthor:: Bernhard Posselt diff --git a/developer_manual/bugtracker/codereviews.rst b/developer_manual/bugtracker/codereviews.rst index 5df3d68d6..4a4deeff8 100644 --- a/developer_manual/bugtracker/codereviews.rst +++ b/developer_manual/bugtracker/codereviews.rst @@ -10,7 +10,7 @@ Introduction In order to increase the code quality within Nextcloud, developers are requested to perform code reviews. As we are now heavily using the GitHub platform these -code review shall take place on GitHub as well. +code reviews shall take place on GitHub as well. Precondition ------------ @@ -32,17 +32,18 @@ How will it work? #. Other developers (either named or at free will) have a look at the changes and are welcome to write comments within the comment field. #. In case the reviewer is okay with the changes and thinks all his comments and - suggestions have been take into account a :+1 on the comment will signal a positive + suggestions have been taken into account a :+1 on the comment will signal a positive review. #. Before a pull request will be merged into master or the corresponding branch at least 2 reviewers need to give :+1 score. -#. Our `continuous integration server`_ will give an additional indicator for - the quality of the pull request. +#. Our continuous integration server will give an additional indicator for + the quality of the pull request (the results can be accessed from the GitHub + interface for that pull request). Examples -------- -Read our `coding guidelines`_ for information on what a good pull request and -good Nextcloud code looks like. +Read our documentation about :doc:`../general/codingguidelines` for information +on what a good pull request and good Nextcloud code looks like. These are two examples that are considered to be good examples of how pull requests should be handled @@ -55,7 +56,5 @@ Questions? Feel free to drop a line on the `forums`_ or join us on `IRC`_. -.. _continuous integration server: https://drone.weasel.rocks/ .. _forums: https://help.nextcloud.com/ .. _IRC: http://webchat.freenode.net/?channels=nextcloud-dev -.. _coding guidelines: ../general/codingguidelines diff --git a/developer_manual/bugtracker/index.rst b/developer_manual/bugtracker/index.rst index 7ea173a42..7aa575b74 100644 --- a/developer_manual/bugtracker/index.rst +++ b/developer_manual/bugtracker/index.rst @@ -15,12 +15,12 @@ Thank you for helping Nextcloud by reporting bugs. Before submitting an issue, p * If the issue is with the Nextcloud server, report it to the `Server repository`_ * If the issue is with the Nextcloud client, report it to the `Client repository`_ -* If the issue with with an Nextcloud app, report it to where that app is developed +* If the issue with with a Nextcloud app, report it to where that app is developed * If the app is listed in our `main GitHub organization`_ report it to the correct sub repository .. _Issue submission guidelines: https://github.com/nextcloud/server/blob/master/CONTRIBUTING.md#submitting-issues -.. _Server repository: https://github.com/nextcloud/server/issues -.. _Client repository: https://github.com/nextcloud/client/issues +.. _Server repository: https://github.com/nextcloud/server/issues +.. _Client repository: https://github.com/nextcloud/client_theming/issues .. _main GitHub organization: https://github.com/nextcloud diff --git a/developer_manual/bugtracker/kanban.rst b/developer_manual/bugtracker/kanban.rst index b9041a5b0..c5fd1bac6 100644 --- a/developer_manual/bugtracker/kanban.rst +++ b/developer_manual/bugtracker/kanban.rst @@ -18,7 +18,7 @@ Backlog Why do we have it? To keep us focused on finishing issues that we started, new issues will be - hidden in this column. In huboard you can see the list of things that we could + hidden in this column. In HuBoard you can see the list of things that we could think about by clicking the small arrow in the top left corner of the concept column header. @@ -57,12 +57,11 @@ When can I pull? documented in a comment to the issue before moving it to the "To develop" step: - * At least one Scenario – written in Gherkin – that tells you and the tester - when the issue is ready to be released. - - * A concept describing the planned implementation. This can be as simple as - a “this just needs changes to the login screen css” or so complex that you - link to a blog entry somewhere else. + * At least one Scenario – written in Gherkin – that tells you and the tester + when the issue is ready to be released. + * A concept describing the planned implementation. This can be as simple as + a “this just needs changes to the login screen CSS” or so complex that you + link to a blog entry somewhere else. Who is Assigned? The maintainer that feels responsible for the issue. @@ -82,7 +81,7 @@ What does a developer think? When can I pull? If you feel like diving into the code and getting your hands dirty you should - look for issues with this label. In the comments, there should be a gherkin + look for issues with this label. In the comments, there should be a Gherkin scenario to tell you when you are done and a concept describing how to implement it. Before you start move the issue to the “Developing” step by assigning the "4 – Developing" label. @@ -121,21 +120,22 @@ To Review Why do we have it? Instead of directly committing to master we agree that **a second set of eyes will spot bugs** and increase our code quality and give us an opportunity to - learn from each other. See also our `Code Review Documentation`_ + learn from each other. See also our documentation about :doc:`codereviews` What does a developer think? "I’ll check the Scenario described earlier works as expected. If necessary I’ll update the related Gherkin Scenarios. `Drone`_ will test the scenario on all kinds of platforms, Web server and database combinations with - `cucumber`_." + `Cucumber`_." When can I pull? If you feel like making sure an issue works as expected you should look for - issues with this label. In the comments you should find a gherkin scenario that + issues with this label. In the comments you should find a Gherkin scenario that can be used as a checklist for what to try. Before you start move the issue to the “Reviewing” step by assigning the “6 – Reviewing” label. -**Who is Assigned?** No one. Especially not if you are working on something else! +Who is Assigned? + No one. Especially not if you are working on something else! Reviewing ~~~~~~~~~ @@ -154,7 +154,7 @@ What does a developer think? manually.* When can I pull? - As long as you are reviewing the issue the you should leave the "6 – + As long as you are reviewing the issue you should leave the "6 – Reviewing" label assigned. Before moving the issue to the "To review" step the issue should have been resolved, meaning that not only the issue has been implemented but also no other functionality has been broken. @@ -182,9 +182,9 @@ Who is Assigned? No one. -While we stated before that said that we push issues to the next column, we can +While we stated before that we push issues to the next column, we can of course move the item back and forth arbitrarily. Basically you can drag the -issue around in the huboard or just change the label when viewing the issue in +issue around in the HuBoard or just change the label when viewing the issue in the GitHub. Reviewing considered impossible? @@ -192,11 +192,11 @@ Reviewing considered impossible? How can you possibly review an issue when it requires you to test various combinations of browsers, platforms, databases and maybe even app combinations? -Well, you can’t. But you can write a gherkin scenario that can be used to write +Well, you can’t. But you can write a Gherkin scenario that can be used to write an automated test that is executed by Drone on every commit to the main repositories. If for some reason Drone cannot be used for the review you will find yourself in the very uncomfortable situation where you release half tested -code that will hopefully not eat user data. Seriously! Write gherkin scenarios! +code that will hopefully not eat user data. Seriously! Write Gherkin scenarios! Other Labels ------------ @@ -241,7 +241,7 @@ Misc Labels * Needs info – Either from a developer or the bug reporter. This is nearly as severe as Panic, because no further action can be taken -* L18n – A translation issue go see our `transifex`_ +* L18n – A translation issue; go see our `Transifex`_ * Junior Job – The issue is considered a good starting point to get involved in Nextcloud development Milestones equal Releases @@ -251,7 +251,7 @@ Releases are planned via milestones which contain all the Enhancements and Bugs that we plan to release when the Deadline is met. When the Deadline approaches we will push new Enhancement request and less important bugs to the next milestone. This way a milestone will upon release contain all the issues that -make up the changelog for the release. Furthermore, huboard allows us to filter +make up the changelog for the release. Furthermore, HuBoard allows us to filter the Kanban board by Milestone, making it especially easy to focus on the current Release. @@ -262,6 +262,6 @@ Release. .. _“Given … when … then …“: https://github.com/cucumber/cucumber/wiki/Given-When-Then .. _unit tests: https://github.com/nextcloud/server/tree/master/tests .. _Code Review Documentation: codereviews -.. _Drone: https://drone.weasel.rocks -.. _cucumber: http://cukes.info/ -.. _transifex: https://www.transifex.com/nextcloud/ +.. _Drone: https://github.com/drone/drone +.. _Cucumber: http://cukes.info/ +.. _Transifex: https://www.transifex.com/nextcloud/ diff --git a/developer_manual/bugtracker/triaging.rst b/developer_manual/bugtracker/triaging.rst index 87a3d67f1..fe57f47be 100644 --- a/developer_manual/bugtracker/triaging.rst +++ b/developer_manual/bugtracker/triaging.rst @@ -6,7 +6,7 @@ Nextcloud Bug Triaging :maxdepth: 2 :hidden: -Bug Triaging is the process of checking bug reports to see if they are still valid (the problem might be solved since the bug was reported), reproducing them when possible (to make sure it really is an Nextcloud issue and not a configuration problem) and in general making sure the bug is useful for a developer who wants to fix it. If the bug is not useful and can't be augmented by the original reporter or the triaging contributor, it has to be closed. +Bug Triaging is the process of checking bug reports to see if they are still valid (the problem might be solved since the bug was reported), reproducing them when possible (to make sure it really is a Nextcloud issue and not a configuration problem) and in general making sure the bug is useful for a developer who wants to fix it. If the bug is not useful and can't be augmented by the original reporter or the triaging contributor, it has to be closed. Why do you want to join ======================= @@ -28,17 +28,17 @@ Triaging follows these steps: * Find an issue somebody should look at * Be that somebody and see if the issue content is useful for a developer -* Reply and close, ask a question, add information or a label. +* Reply and close, ask a question, add information or a label * Find the next bug-to-be-dealt-with and repeat! General considerations ====================== -* You need a `github account `_ to contribute to bug triaging. -* If you are not familiar with the github issue tracker interface (which is used by Nextcloud to handle bug reports), you `may find this guide useful `_. +* You need a `GitHub account `_ to contribute to bug triaging. +* If you are not familiar with the GitHub issue tracker interface (which is used by Nextcloud to handle bug reports), you `may find this guide useful `_. * You will initially only be able to comment on issues. The ability to close issues or assign labels will be given liberally to those who have shown to be willing and able to contribute. Just ask on IRC! * Read `our bug reporting guidelines `_ so you know what a good report should look like and where things belong. The `issue template `_ asks specifically for some information developers need to solve issues. -* It might even be fixed, sometimes! It can also be fruitful to contact the `developers on irc `_. Tell them you're triaging bugs and share what problem you bumped into. Or just ask on the test-pilots mailing list. +* It might even be fixed, sometimes! It can also be fruitful to contact the `developers on IRC `_. Tell them you're triaging bugs and share what problem you bumped into. Or just ask on the test-pilots mailing list. * To ensure no two people are working on the same issue, we ask you to simply add a comment like "I am triaging this" in the issue you want to work on, and when done, before or after executing the triaging actions, note similarly that you're done. To be able to tag and close issues, you need to have access to the repository. For the core and sync app repositories this also means having signed the contributor agreement. However, this isn't really needed for triaging as you can comment after you're done triaging and somebody else can execute those actions. @@ -46,13 +46,13 @@ General considerations Finding bugs to triage ====================== -Github offers several search queries which can be useful to find a list of bugs which deserve a closer look: +GitHub offers several search queries which can be useful to find a list of bugs which deserve a closer look: -* `The bugs least recently commented on `_ -* `Least commented issues `_ -* `Bugs which need info `_ +* `The bugs least recently commented on `_ +* `Least commented issues `_ +* `Bugs which need info `_ -But there are more methods. For example, if you are a user of Nextcloud with a specific setup like using nginx as Web server or dropbox as storage, or using the encryption app, you could look for bugs with these keywords. You can then use your knowledge of your installation and your installation itself to see if bugs are (still) valid or reproduce them. +But there are more methods. For example, if you are a user of Nextcloud with a specific setup like using nginx as Web server or Dropbox as storage, or using the encryption app, you could look for bugs with these keywords. You can then use your knowledge of your installation and your installation itself to see if bugs are (still) valid or reproduce them. Once you have picked an issue, add a comment that you've started triaging: @@ -61,7 +61,7 @@ Once you have picked an issue, add a comment that you've started triaging: Checking if the issue is useful =============================== -Much content from https://techbase.kde.org/Contribute/Bugsquad/Guide_To_BugTriaging +Much content from https://community.kde.org/Guidelines_and_HOWTOs/Bug_triaging The goal of triaging is to have only useful bug reports for the developers. And you don't have to know much to be able to judge at least some bug reports to be less than useful. There are duplications, incomplete reports and so on. Here is the work flow for each bug: @@ -72,7 +72,7 @@ Let's go over each step. Finding duplicates ------------------ -To find duplicates, the search tool in github is your first stop. In `this screen `_ you can easily search for a few keywords from the bug report. If you find other bugs with the same content, decide what the best bug report is (often the oldest or the one where one or more developers have already started to engage and discuss the problem). That is the 'master' bug report, you can now close the other one (or comment that it can be closed as duplicate). +To find duplicates, the search tool in GitHub is your first stop. In `this screen `_ you can easily search for a few keywords from the bug report. If you find other bugs with the same content, decide what the best bug report is (often the oldest or the one where one or more developers have already started to engage and discuss the problem). That is the 'master' bug report, you can now close the other one (or comment that it can be closed as duplicate). If the bug report you were reviewing contains additional information, you can add that information to the 'master' bug report in a comment. Mention this bug report (using #) so a developer can look up the original, closed, report and perhaps ask the initial reporter there for additional information. @@ -82,7 +82,7 @@ When the issue is a feature request, you can be helpful in the same way: merge r .. note:: Be polite: when you need to request information or feedback be clear and polite, and you will get more information in less time. Think about how you'd like to be treated, were you to report a bug! .. note:: You can answer more quickly and friendly using one of `these templates `_. -.. note:: Often our github issue tracker is a place for discussions about solutions. Be friendly, inclusive and respect other people's position. +.. note:: Often our GitHub issue tracker is a place for discussions about solutions. Be friendly, inclusive and respect other people's position. Determining relevance of issue ------------------------------ @@ -121,6 +121,6 @@ Once you are done reproducing an issue, it is time to finish up and make clear t Now, the developers can pick the issue up. Note that while we wish we would always pick up and solve problems promptly, not all areas of Nextcloud get the same amount of attention and contribution, so this can occasionally take a long time. -**Credit:** this document is in debt to the extensive `KDE guide to bug triaging `_. +**Credit:** this document is in debt to the extensive `KDE guide to bug triaging `_. diff --git a/developer_manual/client_apis/OCS/index.rst b/developer_manual/client_apis/OCS/index.rst index cf59d49bb..8a6c5a612 100644 --- a/developer_manual/client_apis/OCS/index.rst +++ b/developer_manual/client_apis/OCS/index.rst @@ -1,4 +1,4 @@ -.. _webdavindex: +.. _ocsapiindex: ========= OCS API's @@ -9,9 +9,9 @@ This document provides a quick overview of the OCS API endpoints supported in Ne 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. @@ -65,3 +65,64 @@ This request returns the available metadata of a user. Admin users can see the i + +---------------- +Capabilities API +---------------- + +Clients can obtain capabilities provided by the Nextcloud server and its apps via the capabilities OCS API. + +.. code:: + + GET /ocs/v1.php/cloud/capabilities + + + +.. code:: xml + + + + + ok + 100 + OK + + + + + + 12 + 0 + 0 + 12.0 beta 4 + + + + + 60 + remote.php/webdav + + + + + + +Theming capabilities +-------------------- + +Values of the theming app are exposed though the capabilities API, allowing client developers to adjust the look of clients to the theming of different Nextcloud instances. + +.. code:: xml + + + Nextcloud + https://nextcloud.com + A safe home for all your data + #0082c9 + http://cloud.example.com/index.php/apps/theming/logo?v=1 + http://cloud.example.com/index.php/apps/theming/logo?v=1 + + + +The background value can either be an URL to the background image or a hex color value. + diff --git a/developer_manual/client_apis/WebDAV/index.rst b/developer_manual/client_apis/WebDAV/index.rst index 2672bded4..b970b8157 100644 --- a/developer_manual/client_apis/WebDAV/index.rst +++ b/developer_manual/client_apis/WebDAV/index.rst @@ -7,17 +7,17 @@ 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. @@ -39,9 +39,9 @@ For example: you can perform a :code:`PROPFIND` request to find files in a folde ' ----- +-------------------------- Listing Folders (rfc4918_) ----- +-------------------------- The contents of a folder can be listed by sending a :code:`PROPFIND` request to the folder. @@ -49,9 +49,9 @@ The contents of a folder can be listed by sending a :code:`PROPFIND` request to 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. @@ -98,15 +98,15 @@ The following properties are supported: - :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. @@ -114,9 +114,9 @@ A file can be downloaded by sending a :code:`GET` request to the WebDAV url of t 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. @@ -126,9 +126,9 @@ A file can be uploading by sending a :code:`PUT` request to the file and sending 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. @@ -136,9 +136,9 @@ A folder can be created by sending a :code:`MKCOL` request to the folder. 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. @@ -148,9 +148,9 @@ A file or folder can be created by sending a :code:`DELETE` request to the 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. @@ -161,9 +161,9 @@ A file or folder can be moved by sending a :code:`MOVE` request to the file or f 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. @@ -174,9 +174,9 @@ A file or folder can be copied by sending a :code:`COPY` request to the file or 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 @@ -194,9 +194,9 @@ A file or folder can be marked as favorite by sending a :code:`PROPPATCH` reques 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 diff --git a/developer_manual/client_apis/index.rst b/developer_manual/client_apis/index.rst index bc9aff355..5f0836bab 100644 --- a/developer_manual/client_apis/index.rst +++ b/developer_manual/client_apis/index.rst @@ -6,9 +6,9 @@ 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` @@ -30,6 +30,6 @@ Other OCS API documentations: :maxdepth: 2 :hidden: - webdav/index - ocs/index + WebDAV/index + OCS/index diff --git a/developer_manual/commun/index.rst b/developer_manual/commun/index.rst index 52f6ace7d..82a633eb1 100644 --- a/developer_manual/commun/index.rst +++ b/developer_manual/commun/index.rst @@ -11,7 +11,7 @@ Communicate via our `forums `_. IRC channels ------------ -Chat with us on `IRC `_. All channels are on **irc.freenode.net** +Chat with us on `IRC `_. All channels are on **irc.freenode.net**: * Setup: **#nextcloud** * Development: **#nextcloud-dev** diff --git a/developer_manual/conf.py b/developer_manual/conf.py index 1a08dcf1a..2062e281a 100644 --- a/developer_manual/conf.py +++ b/developer_manual/conf.py @@ -41,16 +41,16 @@ master_doc = 'index' # General information about the project. project = u'Nextcloud Developer Manual' -copyright = u'2012-2016, The Nextcloud developers' +copyright = u'2012-2017, 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 = '11' +version = '12' # The full version, including alpha/beta/rc tags. -release = '11 alpha' +release = '12' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -254,7 +254,7 @@ texinfo_documents = [ 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' +epub_copyright = u'2012-2017, The Nextcloud developers' # The language of the text. It defaults to the language option # or en if the language is not set. diff --git a/developer_manual/core/externalapi.rst b/developer_manual/core/externalapi.rst index 1b6300661..0dc72095c 100644 --- a/developer_manual/core/externalapi.rst +++ b/developer_manual/core/externalapi.rst @@ -6,38 +6,38 @@ External API Introduction ------------ The external API inside Nextcloud allows third party developers to access data -provided by Nextcloud apps. Nextcloud follows the `OCS v1.7 -specification `_ (draft). +provided by Nextcloud apps. Nextcloud follows the `OpenCloudMesh +specification `_ (draft). Usage ----- Registering Methods ~~~~~~~~~~~~~~~~~~~ -Methods are registered inside the :file:`appinfo/routes.php` using :php:class:`OCP\\API` +Methods are registered inside the :file:`appinfo/routes.php` by returning an +array holding the endpoint meta data. .. code-block:: php [ + // Apps + ['name' => 'Bar#getFoo', 'url' => '/foobar', 'verb' => 'GET'], + ]; Returning Data ~~~~~~~~~~~~~~ Once the API backend has matched your URL, your callable function as defined in -**$action** will be executed. This method is passed as array of parameters that you defined in **$url**. To return data back the the client, you should return an instance of :php:class:`OC_OCS_Result`. The API backend will then use this to construct the XML or JSON response. +**BarController::getFoo** will be executed. The AppFramework will make sure that +send parameters are provided to the method based on its declaration. To return +data back to the client, you should return an instance of (a subclass of) +:php:class:`OCP\AppFramework\Http\Response`, typically :php:class:`OCSResponse`. +The API backend will then use this to construct the XML or JSON response. Authentication & Basics ~~~~~~~~~~~~~~~~~~~~~~~ -Because REST is stateless you have to send user and password each time you access the API. Therefore running Nextcloud **with SSL is highly recommended** otherwise **everyone in your network can log your credentials**:: +Because REST is stateless you have to send user and password each time you access the API. Therefore running Nextcloud **with SSL is highly recommended**; otherwise **everyone in your network can log your credentials**:: https://user:password@example.com/ocs/v1.php/apps/yourapp diff --git a/developer_manual/core/ocs-share-api.rst b/developer_manual/core/ocs-share-api.rst index 45e0b4e63..8b127a933 100644 --- a/developer_manual/core/ocs-share-api.rst +++ b/developer_manual/core/ocs-share-api.rst @@ -5,7 +5,7 @@ OCS Share API The OCS Share API allows you to access the sharing API from outside over pre-defined OCS calls. -The base URL for all calls to the share API is: */ocs/v1.php/apps/files_sharing/api/v1* +The base URL for all calls to the share API is: */ocs/v2.php/apps/files_sharing/api/v1* All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``. @@ -43,7 +43,7 @@ Get all shares from a given file/folder. * Result: XML with the shares -Statuscodes +Statuscodes: * 100 - successful * 400 - not a directory (if the 'subfile' argument was used) @@ -138,7 +138,8 @@ Federated Cloud Shares ====================== Both the sending and the receiving instance need to have federated cloud sharing -enabled and configured. See `Configuring Federated Cloud Sharing `_. +enabled and configured. See `Configuring Federated Cloud Sharing `_. + .. TODO ON RELEASE: Update version number above on release Create a new Federated Cloud Share diff --git a/developer_manual/core/theming.rst b/developer_manual/core/theming.rst index 8b54b7925..8a4eb9102 100644 --- a/developer_manual/core/theming.rst +++ b/developer_manual/core/theming.rst @@ -1,26 +1,20 @@ Theming Nextcloud ================= Themes can be used to customize the look and feel of Nextcloud. -Themes can relate to the following topics of Nextcloud: - -* Theming the web-frontend -* Theming the desktop client - -This documentation contains only the Web-frontend adaptations so far. +.. note:: This is an advanced way of theming Nextcloud; the Nextcloud team recommends instead the use of the `theming app <../../admin_manual/configuration_server/theming.html>` which, when enabled, can be accessed from the Admin settings. Getting started =============== -A good idea getting starting with a dynamically created website is to inspect it with **web developer tools**, that are found in almost any browser. They show the generated HTML and the CSS Code, that the client/browser is receiving: -With this facts you can easily determine, where the following object-related attributes for the phenomenons are settled: +A good idea to get started with a dynamically created website is to inspect it with **web developer tools**, that are found in almost any browser. They show the generated HTML and the CSS Code that the client/browser is receiving: +With this facts you can easily determine where the following object-related attributes for the phenomenons are settled: * place * colour * links * graphics -The next thing you should do, before starting any changes is: -Make a backup of your current theme(s) e.g.: +The next thing you should do, before starting any changes, is to make a backup of your current theme(s), e.g.: * cd …/nextcloud/themes * cp -r example mytheme @@ -30,13 +24,13 @@ Creating and activating a new theme =================================== There are two basic ways of creating new themings: -* Doing all new from scratch -* Starting from an existing theme or the example theme and doing everything step by step and more experimentally +* doing all new from scratch +* starting from an existing theme or the example theme and doing everything step by step and more experimentally -Depending on how you created your new theme it will be necessary to +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 +* 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 @@ -52,13 +46,16 @@ for example in /nextcloud/core/ and /nextcloud/settings/ in these sub folders: * js = JavaScripts * img = images * l10n = translation files -* templates = php and html template files +* templates = PHP and HTML template files .. _notes-for-updates: Notes for Updates ================= + +.. note:: With Nextcloud 12, CSS files have been merged into one server.css so in order to keep your theme working you should consolidate your existing css styles into a server.css file. As for the example theme the styles.css file has been renamed to server.css. + It is not recommended to the user to perform adaptations inside the folder ``/themes/example`` because files inside this folder might get replaced during the next Nextcloud update process. @@ -90,20 +87,19 @@ If you want to do a quick exchange like (1) it's important to know the size of t * Go to the place in the filesystem, that has been shown by the web developer tool/s * You can look up sizing in most cases via the file properties inside your file-manager -* Create an own picture/logo with the same size then +* Create an own picture/logo with the same size as the original photo -The (main) pictures, that can be found inside Nextcloud standard theming are the following: +The (main) pictures that can be found inside Nextcloud standard theming are the following: -* The logo at the login-page above the credentials-box: …/nextcloud/themes/default/core/img/logo.svg -* The logo, that's always in the left upper corner after login: …/nextcloud/themes/default/core/img/logo-wide.svg +* The logo at the login-page above the credentials-box and in the header: …/nextcloud/themes/default/core/img/logo.svg Inserting your new logo ----------------------- Inserting a new logo into an existing theme is as simple as replacing the old logo with the new (generated) one. -You can use: scalable vector graphics (.svg) or common graphics formats for the internet such as portable network graphics (.png) or .jepg +You can use: scalable vector graphics (.svg) or common graphics formats for the Internet such as portable network graphics (.png) or .jpeg. Just insert the new created picture by using the unchanged name of the old picture. -The app icons can also be overwritten in a theme. To change for example the app icon of the activity app you need to overwrite it by saving the new image to …/nextcloud/themes/default/apps/activity/img/activity.svg +The app icons can also be overwritten in a theme. To change for example the app icon of the activity app you need to overwrite it by saving the new image to …/nextcloud/themes/default/apps/activity/img/activity.svg. Changing favicon ---------------- @@ -117,6 +113,31 @@ To customize favicon for MyTheme: Changing the default colours ---------------------------- + +You can inject custom variables into the SCSS generator to apply colors to the default css code by adding the following method to defaults.php: + +.. code-block:: php + + public function getScssVariables() { + return [ + 'color-primary' => '#745bca' + ]; + } + + +The following variables can be overwritten: + +* color-main-text +* color-main-background +* color-primary +* color-primary-text +* color-error +* color-warning +* color-success +* color-loading +* color-loading-dark +* color-box-shadow + With a web-developer tool like Mozilla-Inspector, you also get easily displayed the color of the background you clicked on. On the top of the login page you can see a case- distinguished setting for different browsers: @@ -134,10 +155,10 @@ On the top of the login page you can see a case- distinguished setting for diffe background: linear-gradient(top, #33537a 0%,#1d2d42 100%); /* W3C */ } -The different background-assignments indicate the headers for a lot of different browser types. What you most likely want to do is change the #35537a (lighter blue) and #ld2d42 (dark blue) color to the colours of our choice. In some older and other browsers, there is just one color, but in the rest showing gradients is possible. -The login page background is a horizontal gradient. The first hex number, #35537a, is the top color of the gradient at the login screen. The second hex number, #ld2d42 is the bottom color of the gradient at the login screen. +The different background-assignments indicate the headers for a lot of different browser types. What you most likely want to do is change the #35537a (lighter blue) and #ld2d42 (dark blue) color to the colours of our choice. In some older and other browsers there is just one color, but in the rest showing gradients is possible. +The login page background is a horizontal gradient. The first hex number, #35537a, is the top color of the gradient at the login screen. The second hex number, #ld2d42, is the bottom color of the gradient at the login screen. The gradient in top of the normal view after login is also defined by these CSS-settings, so that they take effect in logged in situation as well. -Change these colors to the hex color of your choice: +Change these colors to the hex color of your choice. As usual: * the first two figures give the intensity of the red channel, @@ -156,7 +177,7 @@ How to change translations You can override the translation of single strings within your theme. Simply create the same folder structure within your theme folder for the language file -you want to override. Only the changed strings need to be added to that file for +you want to override. Only the changed strings need to be added to that file; for all other terms the shipped translation will be used. If you want to override the translation of the term "Download" within the @@ -191,6 +212,15 @@ because the first is needed to enable translations in the JavaScript code and the second one is read by the PHP code and provides the data for translated terms in there. +How to update custom mimetype icons +=================================== + +The following command is required to run after adding custom mimetype icons to your theme: + +.. code-block:: bash + + sudo -u www-data php occ maintenance:mimetype:update-js + How to change names, slogans and URLs ===================================== diff --git a/developer_manual/core/translation.rst b/developer_manual/core/translation.rst index 29e196d87..e389f3d8b 100644 --- a/developer_manual/core/translation.rst +++ b/developer_manual/core/translation.rst @@ -4,9 +4,10 @@ Translation Make text translatable ---------------------- -In HTML or PHP wrap it like this ``t('This is some text'));?>`` or this ``t('This is some text'));?>`` -For the right date format use ``l('date', time()));?>``. Change the way dates are shown by editing /core/l10n/l10n-[lang].php -To translate text in javascript use: ``t('appname','text to translate');`` +In HTML or PHP wrap it like this ``t('This is some text'));?>`` or this ``t('This is some text'));?>``. +For the right date format use ``l('date', time()));?>``. Change the way dates are shown by editing :file:`/core/l10n/l10n-{lang}.php`. + +To translate text in JavaScript use: ``t('appname','text to translate');`` .. note:: ``print_unescaped()`` should be preferred only if you would like to display HTML code. Otherwise, using ``p()`` is strongly preferred to escape HTML characters against XSS attacks. @@ -36,10 +37,10 @@ Translators will translate: Translating these individual strings results in ``local filesystem`` and ``cloud`` losing case. The two white spaces surrounding ``or`` will get lost while translating as well. For languages that have a different grammatical order it prevents the translators from reordering the sentence components. -Html on translation string: +HTML on translation string: ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Html tags in translation strings is ugly but usually translators can handle this. +HTML tags in translation strings is ugly but usually translators can handle this. What about variable in the strings? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -54,26 +55,22 @@ Automated synchronization of translations ----------------------------------------- Multiple nightly jobs have been setup in order to synchronize translations - it's a multi-step process: -``perl l10n.pl read`` will rescan all php and javascript files and generate the templates. -The templates are pushed to `Transifex`_ (tx push -s). -All translations are pulled from `Transifex`_ (tx pull -a). -``perl l10n.pl write`` will write the php files containing the translations. -Finally the changes are pushed to git. + +#. ``perl l10n.pl read`` will rescan all PHP and JavaScript files and generate the templates. +#. The templates are pushed to `Transifex`_ (tx push -s). +#. All translations are pulled from `Transifex`_ (tx pull -a). +#. ``perl l10n.pl write`` will write the PHP files containing the translations. +#. Finally the changes are pushed to Git. Please follow the steps below to add translation support to your app: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Create a folder ``l10n``. -Create the file ``ignorelist`` which can contain files which shall not be scanned during step 4. -Edit ``l10n/.tx/config`` and copy/past a config section and adopt it by changing the app/folder name. -Run ``perl l10n.pl read`` with l10n -Add the newly created translation template (l10n/Templates/.pot) to git and commit the changes above. -After the next nightly sync job a new resource will appear on Transifex and from now on every night the latest translations will arrive. - -Translation sync jobs: -~~~~~~~~~~~~~~~~~~~~~~ - -https://ci.owncloud.org/view/translation-sync/ +#. Create a folder ``l10n``. +#. Create the file ``ignorelist`` which can contain files which shall not be scanned during step 4. +#. Edit ``l10n/.tx/config`` and copy/paste a config section and adapt it by changing the app/folder name. +#. Run ``perl l10n.pl read`` within the folder :file:`l10n`. +#. Add the newly created translation template (*l10n/Templates/.pot*) to Git and commit the changes above. +#. After the next nightly sync job a new resource will appear on Transifex and from now on every night the latest translations will arrive. **Caution: information below is in general not needed!** @@ -84,9 +81,9 @@ Manual quick translation update: cd l10n/ && perl l10n.pl read && tx push -s && tx pull -a && perl l10n.pl write && cd .. -The translation script requires Locale::PO, installable via ``apt-get install liblocale-po-perl`` +The translation script requires Locale::PO, installable via ``apt-get install liblocale-po-perl``. -Configure transifex +Configure Transifex ------------------- .. code-block:: bash diff --git a/developer_manual/core/unit-testing.rst b/developer_manual/core/unit-testing.rst index b20334b99..3c5405f77 100644 --- a/developer_manual/core/unit-testing.rst +++ b/developer_manual/core/unit-testing.rst @@ -9,7 +9,7 @@ Getting PHPUnit Nextcloud uses PHPUnit >= 4.8 for unit testing. -To install it, either get it via your packagemanager:: +To install it, either get it via your package manager:: sudo apt-get install phpunit @@ -19,7 +19,7 @@ or install it manually:: chmod +x phpunit.phar sudo mv phpunit.phar /usr/local/bin/phpunit -After the installation the ''phpunit'' command is available:: +After the installation the **phpunit** command is available:: phpunit --version @@ -34,13 +34,13 @@ Writing PHP unit tests To get started, do the following: - Create a directory called ``tests`` in the top level of your application - - Create a php file in the directory and ``require_once`` your class which you want to test. + - Create a PHP file in the directory and ``require_once`` your class which you want to test -Then you can simply run the created test with phpunit. +Then you can simply run the created test with **phpunit**. -.. note:: If you use Nextcloud functions in your class under test (i.e: OC::getUser()) you'll need to bootstrap Nextcloud or use dependency injection. +.. note:: If you use Nextcloud functions in your class under test (i.e., OC::getUser()) you'll need to bootstrap Nextcloud or use dependency injection. -.. note:: You'll most likely run your tests under a different user than the Web server. This might cause problems with your PHP settings (i.e: open_basedir) and requires you to adjust your configuration. +.. note:: You'll most likely run your tests under a different user than the Web server. This might cause problems with your PHP settings (i.e., open_basedir) and requires you to adjust your configuration. An example for a simple test would be: @@ -84,7 +84,7 @@ In :file:`/srv/http/nextcloud/apps/myapp/` you run the test with:: phpunit tests/testaddtwo.php -Make sure to extend the ``\Test\TestCase`` class with your test and always call the parent methods, +Make sure to extend the ``\Test\TestCase`` class with your test and always call the parent methods when overwriting ``setUp()``, ``setUpBeforeClass()``, ``tearDown()`` or ``tearDownAfterClass()`` method from the TestCase. These methods set up important stuff and clean up the system after the test, so the next test can run without side effects, like remaining files and entries in the file cache, etc. @@ -95,7 +95,7 @@ Bootstrapping Nextcloud ~~~~~~~~~~~~~~~~~~~~~~~ If you use Nextcloud functions or classes in your code, you'll need to make them available to your test by bootstrapping Nextcloud. -To do this, you'll need to provide the ``--bootstrap`` argument when running PHPUnit +To do this, you'll need to provide the ``--bootstrap`` argument when running PHPUnit: :file:`/srv/http/nextcloud`:: @@ -138,7 +138,7 @@ Further Reading JavaScript unit testing for core -------------------------------- -JavaScript Unit testing for **core** and **core apps** is done using the `Karma `_ test runner with `Jasmine `_. +JavaScript Unit testing for **core** and **core apps** is done using the `Karma `_ test runner with `Jasmine `_. Installing Node JS ~~~~~~~~~~~~~~~~~~ @@ -177,9 +177,9 @@ Every time you reload the page, the unit tests will be relaunched and will outpu Unit test paths ~~~~~~~~~~~~~~~ -JavaScript unit test examples can be found in :file:`apps/files/tests/js/` +JavaScript unit test examples can be found in :file:`apps/files/tests/js/`. -Unit tests for the core app JavaScript code can be found in :file:`core/js/tests/specs` +Unit tests for the core app JavaScript code can be found in :file:`core/js/tests/specs`. Documentation ~~~~~~~~~~~~~ diff --git a/developer_manual/general/codingguidelines.rst b/developer_manual/general/codingguidelines.rst index 1a04d7fcf..eeeef1dd5 100644 --- a/developer_manual/general/codingguidelines.rst +++ b/developer_manual/general/codingguidelines.rst @@ -7,12 +7,12 @@ General ------- * Ideally, discuss your plans on the `forums `_ to see if others want to work with you on it -* We use `Github `_, please get an account there and clone the repositories you want to work on +* We use `GitHub `_, please get an account there and clone the repositories you want to work on * Fixes go directly to master, nevertheless they need to be tested thoroughly. * New features are always developed in a branch and only merged to master once they are fully done. * Software should work. We only put features into master when they are complete. It's better to not have a feature instead of having one that works poorly. * It is best to start working based on an issue - create one if there is none. You describe what you want to do, ask feedback on the direction you take it and take it from there. -* When you are finished, use the merge request function on Github to create a pull request. The other developers will look at it and give you feedback. You can signify that your PR is ready for review by adding the label "5 - ready for review" to it. You can also post your merge request to the mailing list to let people know. See `the code review page for more information <../bugtracker/codereviews.html>`_ +* When you are finished, use the merge request function on GitHub to create a pull request. The other developers will look at it and give you feedback. You can signify that your PR is ready for review by adding the label "5 - ready for review" to it. You can also post your merge request to the mailing list to let people know. See `the code review page for more information <../bugtracker/codereviews.html>`_ * It is key to keep changes separate and small. The bigger and more hairy a PR grows, the harder it is to get it in. So split things up where you can in smaller changes - if you need a small improvement like a API addition for a big feature addition, get it in first rather than adding it to the big piece of work! * Decisions are made by consensus. We strive for making the best technical decisions and as nobody can know everything, we collaborate. That means a first negative comment might not be the final word, neither is positive feedback an immediate GO. Nextcloud is built out of modular pieces (apps) and maintainers have a strong influence. In case of disagreement we consult other seasoned contributors. @@ -28,14 +28,14 @@ The most important labels and their meaning: * #design - this needs help from the design team or is a design-related issue/pull request * #technical debt - this issue or PR is about `technical debt `_ * #starter issue - these are issues which are relatively easy to solve and ideal for people who want to learn how to code in Nextcloud -* #needs info - this issue needs further information from the reporter, see `triaging <../bugtracker/triaging.html>`_ +* #needs info - this issue needs further information from the reporter, see :doc:`../bugtracker/triaging` * #high #medium #low signify how important the bug is. * Tags showing the state of the issue or PR, numbered 0-4: - * #0 - Needs triage - ready to start development on this - * #1 - To develop - ready to start development on this - * #2 - Developing - development in progress - * #3 - To Review - ready for review - * #4 - To Release - reviewed PR that awaits unfreeze of a branch to get merged + * #0 - Needs triage - ready to start development on this + * #1 - To develop - ready to start development on this + * #2 - Developing - development in progress + * #3 - To Review - ready for review + * #4 - To Release - reviewed PR that awaits unfreeze of a branch to get merged * Feature tags: #feature: something. These tags indicate the features across apps and components which are impacted by the issue or which the PR is related to If you want a label not in the list above, please first discuss on the mailing list. @@ -131,7 +131,7 @@ All API methods need to be marked with `PHPDoc `_ (**Section**: Manual Installation - Prerequisites). +First `set up your Web server and database `_ (**Section**: Manual Installation - Prerequisites). .. TODO ON RELEASE: Update version number above on release @@ -20,16 +20,17 @@ Get the source There are two ways to obtain Nextcloud sources: -* Using the `stable version `_ -.. TODO ON RELEASE: Update version number above on release +* Using the `stable version `_ * Using the development version from `GitHub`_ which will be explained below. -To check out the source from `GitHub`_ you will need to install git (see `Setting up git `_ from the GitHub help) +.. TODO ON RELEASE: Update version number above on release + +To check out the source from `GitHub`_ you will need to install Git (see `Setting up Git `_ from the GitHub help) Gather information about server setup ------------------------------------- -To get started the basic git repositories need to cloned into the Web server's directory. Depending on the distribution this will either be +To get started the basic Git repositories need to cloned into the Web server's directory. Depending on the distribution this will either be * **/var/www** * **/var/www/html** @@ -52,7 +53,7 @@ After the development tool installation make the directory writable:: sudo chmod o+rw /var/www -Then install Nextcloud from git:: +Then install Nextcloud from Git:: git clone git@github.com:nextcloud/server.git /var/www/ cd /var/www/ @@ -82,7 +83,7 @@ Enabling debug mode .. note:: Do not enable this for production! This can create security problems and is only meant for debugging and development! -To disable JavaScript and CSS caching debugging has to be enabled by setting ``debug`` to ``true`` in :file:`core/config/config.php`:: +To disable JavaScript and CSS caching debugging has to be enabled by setting ``debug`` to ``true`` in :file:`config/config.php`:: @@ -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 `_ 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 `_ or on our IRC channel **#nextcloud-dev** on **irc.freenode.net**. diff --git a/developer_manual/index.rst b/developer_manual/index.rst index 33aad0ecb..8e1ffde09 100644 --- a/developer_manual/index.rst +++ b/developer_manual/index.rst @@ -4,7 +4,7 @@ Nextcloud Developer Documentation ================================= -.. _ownCloud Appstore: https://apps.owncloud.com/ +.. _Nextcloud App Store: https://apps.nextcloud.com/ .. _Translation: https://www.transifex.com/nextcloud/ .. _Documentation: https://github.com/nextcloud/documentation#nextcloud-documentation diff --git a/go.php b/go.php index f864b7a31..fd153eeec 100644 --- a/go.php +++ b/go.php @@ -9,7 +9,6 @@ $mapping = array( 'admin-external-storage' => '/admin_manual/configuration_files/external_storage_configuration_gui.html', 'admin-sharing-federated' => '/admin_manual/configuration_files/federated_cloud_sharing_configuration.html', 'admin-sharing' => '/admin_manual/configuration_files/file_sharing_configuration.html', - 'admin-files-access-control' => '/admin_manual/configuration_files/files_access_control.html', 'admin-transactional-locking' => '/admin_manual/configuration_files/files_locking_transactional.html', 'admin-background-jobs' => '/admin_manual/configuration_server/background_jobs_configuration.html', 'admin-config' => '/admin_manual/configuration_server/config_sample_php_parameters.html', @@ -19,6 +18,9 @@ $mapping = array( 'admin-reverse-proxy' => '/admin_manual/configuration_server/reverse_proxy_configuration.html', 'admin-ldap' => '/admin_manual/configuration_user/user_auth_ldap.html', 'admin-provisioning-api' => '/admin_manual/configuration_user/user_provisioning_api.html', + 'admin-files-access-control' => '/admin_manual/file_workflows/access_control.html', + 'admin-files-automated-tagging' => '/admin_manual/file_workflows/automated_tagging.html', + 'admin-files-retention' => '/admin_manual/file_workflows/retention.html', 'admin-install' => '/admin_manual/installation/index.html', 'admin-dir_permissions' => '/admin_manual/installation/installation_wizard.html#setting-strong-directory-permissions', 'admin-source_install' => '/admin_manual/installation/source_installation.html', @@ -29,6 +31,8 @@ $mapping = array( 'admin-monitoring' => '/admin_manual/operations/considerations_on_monitoring.html', 'admin-sso' => '/admin_manual/configuration_server/sso_configuration.html', 'admin-php-opcache' => '/admin_manual/configuration_server/server_tuning.html#enable-php-opcache', + 'admin-mysql-utf8mb4' => '/admin_manual/configuration_database/mysql_4byte_support.html', + 'admin-update' => '/admin_manual/maintenance/update.html', 'developer-code-integrity'=> '/developer_manual/app/code_signing.html', 'developer-theming' => '/developer_manual/core/theming.html', diff --git a/user_manual/conf.py b/user_manual/conf.py index df8a0fcea..19fc9b6ed 100644 --- a/user_manual/conf.py +++ b/user_manual/conf.py @@ -44,13 +44,13 @@ master_doc = 'contents' # built documents. # # The short X.Y version. -version = '11' +version = '12' # The full version, including alpha/beta/rc tags. -release = '11' +release = '12' # General information about the project. project = u'Nextcloud %s User Manual' % (version) -copyright = u'2012-2016, The Nextcloud developers' +copyright = u'2012-2017, The Nextcloud developers' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -253,7 +253,7 @@ texinfo_documents = [ epub_title = u'Nextcloud User Manual' epub_author = u'The Nextcloud developers' epub_publisher = u'The Nextcloud developers' -epub_copyright = u'2012-2016, The Nextcloud developers' +epub_copyright = u'2012-2017, The Nextcloud developers' # The language of the text. It defaults to the language option # or en if the language is not set. diff --git a/user_manual/external_storage/external_storage.rst b/user_manual/external_storage/external_storage.rst index c52171abf..2b6d9c765 100644 --- a/user_manual/external_storage/external_storage.rst +++ b/user_manual/external_storage/external_storage.rst @@ -6,7 +6,7 @@ The External Storage application allows you to mount external storage services, such as Google Drive, Dropbox, Amazon S3, SMB/CIFS fileservers, and FTP servers in Nextcloud. Your Nextcloud server administrator controls which of these are available to you. Please see `Configuring External Storage (GUI) -`_ in the Nextcloud Administrator's manual for configuration howtos and examples. diff --git a/user_manual/files/access_webdav.rst b/user_manual/files/access_webdav.rst index cf1ecb67a..13120cacb 100644 --- a/user_manual/files/access_webdav.rst +++ b/user_manual/files/access_webdav.rst @@ -188,14 +188,14 @@ path of your certificate as in this example:: servercert /etc/davfs2/certs/mycertificate.pem -Accessing Files Using Mac OS X ------------------------------- +Accessing Files Using macOS +--------------------------- -.. note:: The Mac OS X Finder suffers from a `series of implementation problems +.. note:: The macOS Finder suffers from a `series of implementation problems `_ and should only be used if the Nextcloud server runs on **Apache** and **mod_php**, or **Nginx 1.3.8+**. -To access files through the Mac OS X Finder: +To access files through the macOS Finder: 1. Choose **Go > Connect to Server**. @@ -207,7 +207,7 @@ To access files through the Mac OS X Finder: :alt: Screenshot of entering your Nextcloud server address on Mac OS X For example, the URL used to connect to the Nextcloud server - from the Mac OS X Finder is:: + from the macOS Finder is:: https://example.com/nextcloud/remote.php/dav/files/USERNAME/ diff --git a/user_manual/files/access_webgui.rst b/user_manual/files/access_webgui.rst index 0ea313422..d4e4aee1d 100644 --- a/user_manual/files/access_webgui.rst +++ b/user_manual/files/access_webgui.rst @@ -7,7 +7,7 @@ preview, edit, delete, share, and re-share files. Your Nextcloud administrator has the option to disable these features, so if any of them are missing on your system ask your server administrator. -.. figure:: ../images/files_page.png +.. figure:: ../images/users-files.png :alt: The Files view screen. Tagging Files diff --git a/user_manual/files/desktop_mobile_sync.rst b/user_manual/files/desktop_mobile_sync.rst index 806c6c9ee..53539d26a 100644 --- a/user_manual/files/desktop_mobile_sync.rst +++ b/user_manual/files/desktop_mobile_sync.rst @@ -3,8 +3,7 @@ Desktop and Mobile Synchronization ================================== For synchronizing files with your desktop computer, we recommend using the -`Nextcloud Sync Client`_ for Windows, Mac OS X and Linux until the Nextcloud -Sync Client will be released.. +`Nextcloud Sync Client`_ for Windows, Mac OS X and Linux. The Nextcloud Desktop Sync Client enables you to connect to your Nextcloud Server. @@ -15,10 +14,11 @@ computer, it will flow across the others using these desktop sync clients. You will always have your latest files with you wherever you are. -Its usage is documented separately in the `Nextcloud Desktop Client Manual`_. +Its usage is documented separately in the `Nextcloud/ownCloud Desktop Client Manual`_. -.. _Nextcloud Sync Client: https://nextcloud.com/install/ +.. _`Nextcloud/ownCloud Desktop Client Manual`: https://doc.owncloud.org/desktop/2.2/ .. _Nextcloud Desktop Client Manual: https://docs.nextcloud.org/ +.. _Nextcloud Sync Client: https://nextcloud.com/install/#install-clients Mobile Clients -------------- diff --git a/user_manual/files/encrypting_files.rst b/user_manual/files/encrypting_files.rst index 1bdf9fd2d..cdaf4136f 100644 --- a/user_manual/files/encrypting_files.rst +++ b/user_manual/files/encrypting_files.rst @@ -33,21 +33,31 @@ Encryption FAQ How Can Encryption Be Disabled? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The only way to disable encryption is to run the :ref:`"decrypt all" ` +The only way to disable encryption is to run the `"decrypt all" +`_. + +.. TODO ON RELEASE: Update version number above on release + script, which decrypts all files and disables encryption. Is It Possible To Disable Encryption With The Recovery Key? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Yes, *if* every user uses the :ref:`file recovery key -`, :ref:`"decrypt all" ` will use it -to decrypt all files. +Yes, *if* every user uses the `file recovery key +`_, `"decrypt all" +`_ will use it to decrypt all files. + +.. TODO ON RELEASE: Update version number above on release Can Encryption Be Disabled Without The User’s Password? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -If you don't have the users password or :ref:`file recovery key -` then there is no way to decrypt all files. What's +If you don't have the users password or `file recovery key +`_. + +.. TODO ON RELEASE: Update version number above on release + +then there is no way to decrypt all files. What's more, running it on login would be dangerous, because you would most likely run into timeouts. @@ -105,7 +115,7 @@ the share. This updates the encryption, and then the share owner can remove the individual shares. Recovery Key Password -~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^ If your Nextcloud administrator has enabled the recovery key feature, you can choose to use this feature for your account. If you enable "Password recovery" @@ -132,7 +142,7 @@ There may be other files that are not encrypted; only files that are exposed to third-party storage providers are guaranteed to be encrypted. Change Private Key Password -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^ This option is only available if your log-in password, but not your encryption password, was changed by your administrator. This can occur if your Nextcloud diff --git a/user_manual/files/large_file_upload.rst b/user_manual/files/large_file_upload.rst index 8acd4df03..09f4855ce 100644 --- a/user_manual/files/large_file_upload.rst +++ b/user_manual/files/large_file_upload.rst @@ -15,7 +15,7 @@ set by your administrator): * Contact your administrator to request an increase in these variables * Refer to the section in the `Admin Documentation - `_ that describes how to manage file upload size limits. diff --git a/user_manual/images/CalDAV_calendar.png b/user_manual/images/CalDAV_calendar.png new file mode 100644 index 000000000..acfac9679 Binary files /dev/null and b/user_manual/images/CalDAV_calendar.png differ diff --git a/user_manual/images/addressbook_name.png b/user_manual/images/addressbook_name.png new file mode 100644 index 000000000..6e96142f7 Binary files /dev/null and b/user_manual/images/addressbook_name.png differ diff --git a/user_manual/images/apps_menu.png b/user_manual/images/apps_menu.png new file mode 100644 index 000000000..dacc4b705 Binary files /dev/null and b/user_manual/images/apps_menu.png differ diff --git a/user_manual/images/cardbook_icon.png b/user_manual/images/cardbook_icon.png new file mode 100644 index 000000000..36f40e691 Binary files /dev/null and b/user_manual/images/cardbook_icon.png differ diff --git a/user_manual/images/contact_bottombar.png b/user_manual/images/contact_bottombar.png index 3d91ea982..4d325444a 100644 Binary files a/user_manual/images/contact_bottombar.png and b/user_manual/images/contact_bottombar.png differ diff --git a/user_manual/images/contact_manageaddressbook.png b/user_manual/images/contact_manageaddressbook.png new file mode 100644 index 000000000..1aae2d491 Binary files /dev/null and b/user_manual/images/contact_manageaddressbook.png differ diff --git a/user_manual/images/contact_new.png b/user_manual/images/contact_new.png index 4cef92150..de82ab79d 100644 Binary files a/user_manual/images/contact_new.png and b/user_manual/images/contact_new.png differ diff --git a/user_manual/images/contact_picture.jpg b/user_manual/images/contact_picture.jpg deleted file mode 100644 index 089ac71bf..000000000 Binary files a/user_manual/images/contact_picture.jpg and /dev/null differ diff --git a/user_manual/images/contact_picture.png b/user_manual/images/contact_picture.png index 17e828a95..f1d9eb171 100644 Binary files a/user_manual/images/contact_picture.png and b/user_manual/images/contact_picture.png differ diff --git a/user_manual/images/contact_picture_default.png b/user_manual/images/contact_picture_default.png deleted file mode 100644 index 24802de2c..000000000 Binary files a/user_manual/images/contact_picture_default.png and /dev/null differ diff --git a/user_manual/images/contact_picture_options.png b/user_manual/images/contact_picture_options.png new file mode 100644 index 000000000..4a5af0051 Binary files /dev/null and b/user_manual/images/contact_picture_options.png differ diff --git a/user_manual/images/contact_picture_set.png b/user_manual/images/contact_picture_set.png new file mode 100644 index 000000000..bf6b600a6 Binary files /dev/null and b/user_manual/images/contact_picture_set.png differ diff --git a/user_manual/images/contact_thunderbird-Symbol_Gear.jpg b/user_manual/images/contact_thunderbird-Symbol_Gear.jpg deleted file mode 100755 index d9f60413c..000000000 Binary files a/user_manual/images/contact_thunderbird-Symbol_Gear.jpg and /dev/null differ diff --git a/user_manual/images/contact_thunderbird-Symbol_Impeller.jpg b/user_manual/images/contact_thunderbird-Symbol_Impeller.jpg deleted file mode 100755 index a3e7fe53b..000000000 Binary files a/user_manual/images/contact_thunderbird-Symbol_Impeller.jpg and /dev/null differ diff --git a/user_manual/images/contact_thunderbird-URL_config.jpg b/user_manual/images/contact_thunderbird-URL_config.jpg deleted file mode 100755 index 9ab48faaf..000000000 Binary files a/user_manual/images/contact_thunderbird-URL_config.jpg and /dev/null differ diff --git a/user_manual/images/contact_uploadbutton.png b/user_manual/images/contact_uploadbutton.png index ce9027551..ee5b7e633 100644 Binary files a/user_manual/images/contact_uploadbutton.png and b/user_manual/images/contact_uploadbutton.png differ diff --git a/user_manual/images/contacts_empty.png b/user_manual/images/contacts_empty.png index 70f045cf3..f08a526ae 100644 Binary files a/user_manual/images/contacts_empty.png and b/user_manual/images/contacts_empty.png differ diff --git a/user_manual/images/contacts_link.png b/user_manual/images/contacts_link.png new file mode 100644 index 000000000..3e9ed8252 Binary files /dev/null and b/user_manual/images/contacts_link.png differ diff --git a/user_manual/images/contacts_menu.png b/user_manual/images/contacts_menu.png new file mode 100644 index 000000000..3d01b9200 Binary files /dev/null and b/user_manual/images/contacts_menu.png differ diff --git a/user_manual/images/contacts_popup.png b/user_manual/images/contacts_popup.png new file mode 100644 index 000000000..c81df4bbe Binary files /dev/null and b/user_manual/images/contacts_popup.png differ diff --git a/user_manual/images/contacts_settings.png b/user_manual/images/contacts_settings.png deleted file mode 100644 index a42659e0a..000000000 Binary files a/user_manual/images/contacts_settings.png and /dev/null differ diff --git a/user_manual/images/direct-share-1.png b/user_manual/images/direct-share-1.png index f2f8151a4..4575b3c6a 100644 Binary files a/user_manual/images/direct-share-1.png and b/user_manual/images/direct-share-1.png differ diff --git a/user_manual/images/file_menu_comments_2.png b/user_manual/images/file_menu_comments_2.png index aac661276..9a5de708d 100644 Binary files a/user_manual/images/file_menu_comments_2.png and b/user_manual/images/file_menu_comments_2.png differ diff --git a/user_manual/images/files_page-1.png b/user_manual/images/files_page-1.png index 8e4f49f88..a07c7b580 100644 Binary files a/user_manual/images/files_page-1.png and b/user_manual/images/files_page-1.png differ diff --git a/user_manual/images/files_page-2.png b/user_manual/images/files_page-2.png index 20f95cc82..1ae8cad68 100644 Binary files a/user_manual/images/files_page-2.png and b/user_manual/images/files_page-2.png differ diff --git a/user_manual/images/files_page-3.png b/user_manual/images/files_page-3.png index 76aa51843..e7c8e9876 100644 Binary files a/user_manual/images/files_page-3.png and b/user_manual/images/files_page-3.png differ diff --git a/user_manual/images/files_page-4.png b/user_manual/images/files_page-4.png index 04ea7b014..dd86072ff 100644 Binary files a/user_manual/images/files_page-4.png and b/user_manual/images/files_page-4.png differ diff --git a/user_manual/images/files_page-5.png b/user_manual/images/files_page-5.png index 26a42fa3e..923c7cdfa 100644 Binary files a/user_manual/images/files_page-5.png and b/user_manual/images/files_page-5.png differ diff --git a/user_manual/images/files_page-6.png b/user_manual/images/files_page-6.png index 1446ffafb..b72bc2745 100644 Binary files a/user_manual/images/files_page-6.png and b/user_manual/images/files_page-6.png differ diff --git a/user_manual/images/files_page-7.png b/user_manual/images/files_page-7.png index 02cf3aaee..9e6ad1658 100644 Binary files a/user_manual/images/files_page-7.png and b/user_manual/images/files_page-7.png differ diff --git a/user_manual/images/files_page-8.png b/user_manual/images/files_page-8.png index 01b9ab767..01733f6e4 100644 Binary files a/user_manual/images/files_page-8.png and b/user_manual/images/files_page-8.png differ diff --git a/user_manual/images/files_page.png b/user_manual/images/files_page.png index 07bde3d36..435cca153 100644 Binary files a/user_manual/images/files_page.png and b/user_manual/images/files_page.png differ diff --git a/user_manual/images/files_versioning.png b/user_manual/images/files_versioning.png index 6464fc6e3..e1043e8bc 100644 Binary files a/user_manual/images/files_versioning.png and b/user_manual/images/files_versioning.png differ diff --git a/user_manual/images/login_page.png b/user_manual/images/login_page.png new file mode 100644 index 000000000..8efbcab4f Binary files /dev/null and b/user_manual/images/login_page.png differ diff --git a/user_manual/images/multi_sharing.png b/user_manual/images/multi_sharing.png new file mode 100644 index 000000000..9700208d4 Binary files /dev/null and b/user_manual/images/multi_sharing.png differ diff --git a/user_manual/images/new_addressbook.png b/user_manual/images/new_addressbook.png new file mode 100644 index 000000000..0aa65996d Binary files /dev/null and b/user_manual/images/new_addressbook.png differ diff --git a/user_manual/images/new_calendar.png b/user_manual/images/new_calendar.png new file mode 100644 index 000000000..c6753e086 Binary files /dev/null and b/user_manual/images/new_calendar.png differ diff --git a/user_manual/images/oc_connect.png b/user_manual/images/oc_connect.png deleted file mode 100644 index 1e7144ea3..000000000 Binary files a/user_manual/images/oc_connect.png and /dev/null differ diff --git a/user_manual/images/oc_filesweb_new.png b/user_manual/images/oc_filesweb_new.png deleted file mode 100644 index 0c9535c0b..000000000 Binary files a/user_manual/images/oc_filesweb_new.png and /dev/null differ diff --git a/user_manual/images/oc_personal_settings_dropdown.png b/user_manual/images/oc_personal_settings_dropdown.png index 5ca66db69..c6404f40e 100644 Binary files a/user_manual/images/oc_personal_settings_dropdown.png and b/user_manual/images/oc_personal_settings_dropdown.png differ diff --git a/user_manual/images/oc_personal_settings_window.png b/user_manual/images/oc_personal_settings_window.png index 3cc0aa376..eda0f6652 100644 Binary files a/user_manual/images/oc_personal_settings_window.png and b/user_manual/images/oc_personal_settings_window.png differ diff --git a/user_manual/images/oc_share_expiration_calendar.png b/user_manual/images/oc_share_expiration_calendar.png index 1406c57ad..dd09abcfd 100644 Binary files a/user_manual/images/oc_share_expiration_calendar.png and b/user_manual/images/oc_share_expiration_calendar.png differ diff --git a/user_manual/images/osx_webdav1.png b/user_manual/images/osx_webdav1.png index 29279e268..0967693e1 100644 Binary files a/user_manual/images/osx_webdav1.png and b/user_manual/images/osx_webdav1.png differ diff --git a/user_manual/images/osx_webdav2.png b/user_manual/images/osx_webdav2.png index b67e66ae8..15914762d 100644 Binary files a/user_manual/images/osx_webdav2.png and b/user_manual/images/osx_webdav2.png differ diff --git a/user_manual/images/personal_settings.png b/user_manual/images/personal_settings.png index 1ee6bd277..4415de6bf 100644 Binary files a/user_manual/images/personal_settings.png and b/user_manual/images/personal_settings.png differ diff --git a/user_manual/images/quota1.png b/user_manual/images/quota1.png index f05b825dc..607610fb1 100644 Binary files a/user_manual/images/quota1.png and b/user_manual/images/quota1.png differ diff --git a/user_manual/images/synchronize_cardbook.png b/user_manual/images/synchronize_cardbook.png new file mode 100644 index 000000000..b761c4dcc Binary files /dev/null and b/user_manual/images/synchronize_cardbook.png differ diff --git a/user_manual/images/webdav_dolphin.png b/user_manual/images/webdav_dolphin.png index 21afa6451..2ce7adc68 100644 Binary files a/user_manual/images/webdav_dolphin.png and b/user_manual/images/webdav_dolphin.png differ diff --git a/user_manual/pim/contacts.rst b/user_manual/pim/contacts.rst index 71bf6af17..25fc77644 100644 --- a/user_manual/pim/contacts.rst +++ b/user_manual/pim/contacts.rst @@ -3,4 +3,107 @@ Using the Contacts App ====================== The Contacts app is not enabled by default in Nextcloud |version| and needs to -be enabled separately. \ No newline at end of file +be installed separately from our App Store. + +The Nextcloud Contacts app is similar to other mobile contact applications, but +with more functionality. When you first access the Contacts app, a default +address book becomes available. + +.. figure:: ../images/contacts_empty.png + + **Contacts app (empty)** + +Adding Contacts +--------------- +You can add contacts using one of the following methods: + +* Import contacts using a Variant Call Format (VCF) file + +* Add contacts manually + +Importing Contacts +~~~~~~~~~~~~~~~~~~ + +The fastest way to add contacts is through the use of a Variant Call Format +(VCF) file. + +To import contacts using a VCF file: + +1. At the bottom of the Contacts app information field, locate the gear button. + + .. figure:: ../images/contact_bottombar.png + + **Contact settings gear button** + +2. Click the gear button. The Contacts app upload field opens. + +.. figure:: ../images/contact_uploadbutton.png + +**Contacts app upload field** + +Creating Contacts Manually +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Contacts app enables you to create contacts manually. + +To create a new contact: + +1. Click the ``+ New contact`` button. + + An empty new contact configuration opens in the Application View field. + + .. figure:: ../images/contact_new.png + +2. Specify the new contact information. Changes that you made are implemented immediately. + +Edit or Remove Contact Information +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The Contacts app enables you to edit or remove contact information. + +To edit or remove contact information: + +1. Navigate to the specific contact that you want to modify. + +2. Select the information in the field that you want to edit or remove. + +3. Make your modifications or click on the trash bin. + +Changes or removals that you made to any contact information are implemented immediately. + +Contact Picture +~~~~~~~~~~~~~~~ + +To define a contact picture, click on the upload button: + +.. figure:: ../images/contact_picture.png + + **Contact picture (upload button)** + +After you have set a contact picture, it will look like that: + +.. figure:: ../images/contact_picture_set.png + + **Contact picture (set)** + +If you want to upload a new one, remove it, view it in full size or download it +click on the contacts picture. + +.. figure:: ../images/contact_picture_options.png + +Adding and Managing Address Books +--------------------------------- + +Clicking on the settings (gear) button at the bottom of the Apps Information +field provides access to the Contact app settings. This field shows all +available address books, certain options for each address book, and enables you +to create new address books, simply by specifying an address books name. + +.. figure:: ../images/contact_manageaddressbook.png + + **Add address book in the contacts settings** + +The Contacts settings also enables you to share, export and delete address +books. You will also find the CardDAV URLs there. +See :doc:`index` for more details about syncing your adress books +with iOS, macOS, Thunderbird and other CardDAV clients. diff --git a/user_manual/pim/sync_ios.rst b/user_manual/pim/sync_ios.rst index 963665e9a..bea4a89ca 100644 --- a/user_manual/pim/sync_ios.rst +++ b/user_manual/pim/sync_ios.rst @@ -52,5 +52,5 @@ Now should now find your contacts in the address book of your iPhone. If it's still not working, have a look at the :doc:`troubleshooting` and `Troubleshooting Contacts & Calendar`_ guides. -.. _Troubleshooting Contacts & Calendar: https://docs.nextcloud.org/server/11/admin_manual/issues/index.html#troubleshooting-contacts-calendar +.. _Troubleshooting Contacts & Calendar: https://docs.nextcloud.org/server/12/admin_manual/issues/index.html#troubleshooting-contacts-calendar .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/pim/sync_osx.rst b/user_manual/pim/sync_osx.rst index 84336f923..6f8cf4aea 100644 --- a/user_manual/pim/sync_osx.rst +++ b/user_manual/pim/sync_osx.rst @@ -46,5 +46,5 @@ There is also an easy `HOWTO`_ in the forum. .. _HOWTO: https://forum.owncloud.org/viewtopic.php?f=3&t=132 -.. _Troubleshooting Contacts & Calendar: https://docs.nextcloud.org/server/11/admin_manual/issues/index.html#troubleshooting-contacts-calendar +.. _Troubleshooting Contacts & Calendar: https://docs.nextcloud.org/server/12/admin_manual/issues/index.html#troubleshooting-contacts-calendar .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual/pim/sync_thunderbird.rst b/user_manual/pim/sync_thunderbird.rst index f7e41f38e..96cc30210 100644 --- a/user_manual/pim/sync_thunderbird.rst +++ b/user_manual/pim/sync_thunderbird.rst @@ -1,44 +1,64 @@ -Thunderbird - Synchronize Addressbook +Thunderbird - Synchronize Addressbook and Calendar ===================================== Addressbook ----------- -As someone who is new to Nextcloud, new to SoGo Connector, and new to Thunderbird Addressbook... here is what you need in excruciating pithy detail to make this work (for all the other lost souls out there): +As someone who is new to Nextcloud and new to CardBook here is what you need in excruciating pithy detail to make this work: -#. `Thunderbird `_ for your OS unless it comes with your OS distribution (Linux) -#. `Sogo Connector `_ (latest release) -#. `Lightning `_ (a Thunderbird calendar add-on. At the time (Aug 14), syncing your contacts only works with this add-on installed.) +- `Thunderbird `_ for your OS unless it comes with your OS distribution (Linux) +- `CardBook `_ (a Thunderbird contacts add-on.) -With an installed Thunderbird mailtool, an installed SoGo Connector, and an installed Lightning add-on: +Once you've installed CardBook and Thunderbird do like this: -#. Thunderbird Addressbook is in the Thunderbird "Tools" Menu -#. In the Thunderbird Addressbook application: +1. In the bottom left of the Contacts View (in Nextcloud contatcs) look for a little impeller symbol that looks like this: - - "File > New > **Remote Addressbook**" (SoGo Connector added this) - - "**Name:**" is the name you want to give your Addressbook in the Thunderbird addressbook bar area - - "**URL:**" is found in your Nextcloud Contacts area, that little Gear symbol +.. image:: ../images/contacts_link.png -.. image:: ../images/contact_thunderbird-Symbol_Gear.jpg +which will display and URL that looks something like this: +https://cloud.nextcloud.com/remote.php/dav/addressbooks/users/daniel/Thunderbird/ -in the bottom left of the Contacts View (same symbol as found in the top right in the Calendar view). Then look for a little impeller symbol +2. Cardbook is found in the upper right corner of Thunderbird: -.. image:: ../images/contact_thunderbird-Symbol_Impeller.jpg +.. image:: ../images/cardbook_icon.png -which will display the URL you need for your installation to work. +3. In the Thunderbird Cardbook add-on: -.. image:: ../images/contact_thunderbird-URL_config.jpg + - "Adressbook > New Adressbook **Remote** > Next + - Fill in your information -Once installed, synchronize (right click on your newly made remote address book and select "Synchronize"). -You'll see your address book populate from Nextcloud! Don't click "read only" above unless you don't want to -modify your Nextcloud server addressbook, like it contains a listing of corporate contacts and is shared with -lots of people, and you don't want a new user dragging it somewhere unintended. +.. image:: ../images/new_addressbook.png -The rest of the details of dealing with Thunderbird addressbook are left to the reader... First thing I learned -is dragging a contact to a different addressbook is a "move" operation. If you are worried about losing the -contact, save it to a VCF file using Nextcloud (Or LDIF using Thunderbird Addressbook) first! Like dragging -from "Nextcloud Addressbook" to "Personal Address Book" removes the contact from Nextcloud Server -(*deleting it from all the other synchronized installations*) and puts it in your Local Machine -only- -Address Book. So be careful or you'll have unintended consequences where you might have intended a "copy" operation. +4. Validate your settings and click Next, then choose the name of the addressbook and click Next again. -Contact *Pictures* are also sync'ed! +.. image:: ../images/addressbook_name.png + +5. Once installed, synchronize your addressbook by clicking "Synchronize" in the top left corner of CardBook. +You'll see your address book populate from Nextcloud! + +.. image:: ../images/synchronize_cardbook.png + +The rest of the details of dealing with Thunderbird CardBook are left to the reader... + +Calendar +----------- + +- `Thunderbird `_ for your OS unless it comes with your OS distribution (Linux) +- `Lightning `_ (a Thunderbird calendar add-on.) + +Once you've installed Lighning and Thunderbird do like this: + +1. Go to your Nextcloud Calendar and click on the 3 dotted menu for the calendar that you want to synchronize which will display and URL that looks something like this: +https://cloud.nextcloud.com/remote.php/dav/calendars/daniel/personal/ + +2. Go to the calendar view in Thunderbird and right click in the calendar menu to the left (where the names of the calendars are) to add a **New Calendar**. + +3. Choose **On the network** + +.. image:: ../images/new_calendar.png + +4. Choose **CalDAV** and fill in the missing information: + +.. image:: ../images/CalDAV_calendar.png + +The rest of the details of dealing with Thunderbird Calendar are left to the reader... diff --git a/user_manual/user_2fa.rst b/user_manual/user_2fa.rst index 3fbd3984b..f13d11dda 100644 --- a/user_manual/user_2fa.rst +++ b/user_manual/user_2fa.rst @@ -60,8 +60,8 @@ enter the TOTP code in your browser. Just enter your code: If the code was correct you will be redirected to your Nextcloud account. .. note:: Since the code is time-based, it’s important that your server’s and -your smartphone’s clock are almost in sync. A time drift of a few seconds -won’t be a problem. + your smartphone’s clock are almost in sync. A time drift of a few seconds + won’t be a problem. Using client applications with two-factor authentication ======================================================== diff --git a/user_manual/webinterface.rst b/user_manual/webinterface.rst index 8cb53c647..f2a18fcc0 100644 --- a/user_manual/webinterface.rst +++ b/user_manual/webinterface.rst @@ -6,18 +6,15 @@ You can connect to your Nextcloud server using any Web browser; just point it to your Nextcloud server and enter your username and password. Supported Web browsers are: -* Firefox 14+ -* Chrome 18+ -* Safari 7+ -* IE11+ -* Microsoft Edge +* **Mozilla Firefox** 14+ +* **Google Chrome/Chromium** 18+ +* **Safari** 7+ +* **Internet Explorer** 11+ +* **Microsoft Edge** - .. figure:: images/oc_connect.png + .. figure:: images/login_page.png :alt: Nextcloud login screen. -.. note:: Some apps like ``files_external`` or ``encryption`` will disable - the **Stay logged in** checkbox. - Navigating the Main User Interface ---------------------------------- @@ -31,39 +28,44 @@ you (if you are administering the server) or by your server administrator. The Nextcloud user interface contains the following fields and functions: -* **Apps Selection Menu**: Located in the upper left corner, click the arrow to - open a dropdown menu to navigate to your various available apps. +* **Apps Selection Menu** (1): Located in the upper left corner, you'll find all + your apps which are available on your instance of Nextcloud. Clicking on an + apps icon will redirect you to the app. -* **Apps Information** field: Located in the left sidebar, this provides +* **Apps Information** field (2): Located in the left sidebar, this provides filters and tasks associated with your selected app. For example, when you are using the Files apps you have a special set of filters for quickly finding your files, such as files that have been shared with you, and files that you have shared with others. You'll see different items for other apps. -* **Application View**: The main central field in the Nextcloud user interface. +* **Application View** (3): The main central field in the Nextcloud user interface. This field displays the contents or user features of your selected app. -* **Navigation Bar**: Located over the main viewing window (the Application +* **Navigation Bar** (4): Located over the main viewing window (the Application View), this bar provides a type of breadcrumbs navigation that enables you to migrate to higher levels of the folder hierarchy up to the root level (home). -* **New** button: Located in the Navigation Bar, the ``New`` button +* **New** button (5): Located in the Navigation Bar, the ``New`` button enables you to create new files, new folders, or upload files. .. note:: You can also drag and drop files from your file manager into the - Nextcloud Files Application View to upload them to Nextcloud. Currently, + Files Application View to upload them to your instance. Currently, the only Web browsers that support drag-and-drop folders are Chrome and Chromium. -* **Search** field: Click on the magnifier in the upper right hand corner of +* **Search** field (6): Click on the magnifier in the upper right hand corner of to search for files. -* **Gallery** button. This looks like four little squares, and takes you +* **Contacts Menu** (7): Gives you an overview about your contacts and users on + your server. Dependent on the given details and available apps, you can + directly start a video call with them or send emails. + +* **Gallery** button (8). This looks like four little squares, and takes you directly to your image gallery. -* **Personal Settings** menu: Click on your Nextcloud username, located to the - right of the Search field, to open your Personal Settings dropdown menu. Your - Personal page provides the following settings and features: +* **Personal Settings** menu (9): Click on the gear icon or your profile picture, + located to the right of the Search field, to open your Personal Settings + dropdown menu. Your Personal page provides the following settings and features: * Links to download desktop and mobile apps * Re-run the First Run Wizard @@ -74,9 +76,9 @@ The Nextcloud user interface contains the following fields and functions: * Group memberships * Interface language settings * Manage notifications - * Federated Cloud ID - * Social media sharing buttons - * SSL certificate manager + * Federated Cloud ID and social media-sharing buttons + * SSL certificate manager for external storages + * Your Two-factor Settings * Nextcloud Version information See :doc:`userpreferences` section to learn more about these settings. diff --git a/user_manual/whats_new.rst b/user_manual/whats_new.rst index ce9e18be0..d73992fa6 100644 --- a/user_manual/whats_new.rst +++ b/user_manual/whats_new.rst @@ -2,6 +2,24 @@ What's New for Users in Nextcloud |version| =========================================== -* Option to hide or expose hidden files in the Web GUI +1. Easier way to select a new app + .. figure:: images/apps_menu.png + :alt: screenshot of apps menu at top-left of Nextcloud Web GUI + +2. New Contacts menu to reach your colleagues or friends easier + .. figure:: images/contacts_menu.png + :alt: screenshot of contacts menu at top-right of Nextcloud Web GUI + +3. A contact popup menu over avatars everywhere + + .. figure:: images/contacts_popup.png + :alt: screenshot of popup over avatar + +4. Ability to sent multiple unique sharing links each with their own settings, by entering email addresses (the recipient will receive an email) + + .. figure:: images/multi_sharing.png + :alt: screenshot of multiple sharing links + +5. Many other improvements and new apps, like screensharing in Video calls, new Circles app for user defined groups, push notifications, notifications of file changes even when shared to another server, undo removal of files from a shared folder even if the removal was done by a recipient, directly sharing to social media and much more. diff --git a/user_manual_de/conf.py b/user_manual_de/conf.py index 4e7381546..818199325 100644 --- a/user_manual_de/conf.py +++ b/user_manual_de/conf.py @@ -44,13 +44,13 @@ master_doc = 'contents' # built documents. # # The short X.Y version. -version = '11' +version = '12' # The full version, including alpha/beta/rc tags. -release = '11' +release = '12' # General information about the project. project = u'Nextcloud %s Benutzerhandbuch' % (version) -copyright = u'2012-2016, Die Nextcloud Entwickler' +copyright = u'2012-2017, Die Nextcloud Entwickler' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -253,7 +253,7 @@ texinfo_documents = [ epub_title = u'Nextcloud Benutzerhandbuch' epub_author = u'Die Nextcloud Entwickler' epub_publisher = u'Die Nextcloud Entwickler' -epub_copyright = u'2012-2016, Die Nextcloud Entwickler' +epub_copyright = u'2012-2017, Die Nextcloud Entwickler' # The language of the text. It defaults to the language option # or en if the language is not set. diff --git a/user_manual_de/external_storage/external_storage.rst b/user_manual_de/external_storage/external_storage.rst index d9abfcbad..f546f5c3e 100644 --- a/user_manual_de/external_storage/external_storage.rst +++ b/user_manual_de/external_storage/external_storage.rst @@ -5,6 +5,6 @@ Einrichten externer Speicher Mithilfe der "Externe Speicher"-App können Sie externen Speicher von z.B. Google Drive, Dropbox, Amazon S3, SMB/CIFS Fileservern sowie FTP-Servern in Ihre Nextcloud einbinden. Ihr Nextcloud-Administrator kann einstellen, welche dieser Anbieter verwendet werden -können. Mehr dazu finden Sie unter `Externen Speicher verwalten (GUI) `_. +können. Mehr dazu finden Sie unter `Externen Speicher verwalten (GUI) `_. .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual_de/files/encrypting_files.rst b/user_manual_de/files/encrypting_files.rst index dc8078027..68db91dab 100644 --- a/user_manual_de/files/encrypting_files.rst +++ b/user_manual_de/files/encrypting_files.rst @@ -32,22 +32,22 @@ Häufig gestellte Fragen zur Verschlüsselung Wie kann die Verschlüsselung deaktiviert werden? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Um die Verschlüsselung zu deaktivieren müssen Sie das :ref:`"alles entschlüsseln" -`-Skript ausführen, welches alle Daten wieder entschlüsselt und +Um die Verschlüsselung zu deaktivieren müssen Sie das `"alles entschlüsseln" +<../../admin_manual/configuration_server/occ_command.html#encryption-label>`_-Skript ausführen, welches alle Daten wieder entschlüsselt und die Verschlüsselung anschließend deaktiviert. Kann die Verschlüsselung mithilfe des Wiederherstellungs-Schlüssels deaktiviert werden? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Ja, *falls* jeder Nutzer den :ref:`Datei-Wiederherstellungs-Schlüssel -` verwendet, können unter Verwendung des :ref:`"alles entschlüsseln" -`-Skripts alle Daten wieder entschlüsselt werden. +Ja, *falls* jeder Nutzer den `Datei-Wiederherstellungs-Schlüssel +<../../admin_manual/configuration_files/encryption_configuration.html#enabling-users-file-recovery-keys>`_ verwendet, können unter Verwendung des `"alles entschlüsseln" +<../../admin_manual/configuration_server/occ_command.html#encryption-label>`_-Skripts alle Daten wieder entschlüsselt werden. Kann die Verschlüsselung ohne das Passwort eines Nutzers deaktiviert werden? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Sollte das Passwort eines Nutzers oder sein :ref:`Datei-Wiederherstellungs-Schlüssel -` unbekannt sein, können die Daten dieses Nutzers nicht +Sollte das Passwort eines Nutzers oder sein `Datei-Wiederherstellungs-Schlüssel +<../../admin_manual/configuration_files/encryption_configuration.html#enabling-users-file-recovery-keys>`_ unbekannt sein, können die Daten dieses Nutzers nicht wieder entschlüsselt werden. Eine Entschlüsselung unmittelbar nach dem Login wäre gefährlich, da die Entschlüsselung sehr wahrscheinlich aufgrund einer Zeitüberschreitung abgebrochen werden würde. @@ -101,7 +101,7 @@ Zugriff auf diese Daten mehr hat. Dies aktualisiert die Verschlüsselung, wonach Teilen mit diesem Nutzer wieder deaktiviert werden kann. Wiederherstellungs-Schlüssel -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Wenn Ihr Nextcloud-Administrator die Wiederstellungs-Schlüssel-Funktion aktiviert hat, können Sie die Funktion für Ihren Account aktivieren. Wenn Sie "Password-Wiederherstellung" @@ -128,7 +128,7 @@ Es kann weitere Daten geben, die nicht verschlüsselt werden; Daten, die bei ext Speicheranbietern gesichert werden, sind auf jeden Fall verschlüsselt. Ändern des Passworts -~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^ Diese Option ist verfügbar, sollte Ihr Administrator Ihr Login-Passwort (aber nicht das Passwort zum Verschlüsseln Ihrer Daten) geändert haben. Dies kann z.B. dann der Fall sein, diff --git a/user_manual_de/files/large_file_upload.rst b/user_manual_de/files/large_file_upload.rst index ff2e440ff..5a3987631 100644 --- a/user_manual_de/files/large_file_upload.rst +++ b/user_manual_de/files/large_file_upload.rst @@ -15,6 +15,6 @@ der vom Administrator festgelegten Größe erlaubt wird: * Wenden Sie sich an Ihren Administrator, um eine Erhöhung dieser Variablen anzufordern -* Lesen Sie den Abschnitt in der `Admin-Dokumentation `_ , in dem beschrieben wird, wie die Größenbeschränkungen für die Dateigröße zu verwalten sind. +* Lesen Sie den Abschnitt in der `Admin-Dokumentation `_ , in dem beschrieben wird, wie die Größenbeschränkungen für die Dateigröße zu verwalten sind. .. TODO ON RELEASE: Update version number above on release diff --git a/user_manual_de/pim/index.rst b/user_manual_de/pim/index.rst index ea8689429..5314e7038 100644 --- a/user_manual_de/pim/index.rst +++ b/user_manual_de/pim/index.rst @@ -12,6 +12,5 @@ können diese Apps aber mit einem Klick auf "Aktivieren" unter Apps -> Produktiv calendar sync_ios sync_osx - sync_kde sync_thunderbird troubleshooting