[Pkg-owncloud-commits] [owncloud-doc] 68/110: Corrections to occ docs
David Prévot
taffit at moszumanska.debian.org
Fri Feb 6 21:10:36 UTC 2015
This is an automated email from the git hooks/post-receive script.
taffit pushed a commit to branch master
in repository owncloud-doc.
commit 7ced273c5fd6feecba6ba092d367ab1a6fa00e57
Author: Carla Schroder <carla at owncloud.com>
Date: Tue Jan 13 19:40:02 2015 -0800
Corrections to occ docs
---
admin_manual/configuration/occ_command.rst | 132 ++++++++++++++++-------------
admin_manual/maintenance/convert_db.rst | 58 ++++++++-----
admin_manual/maintenance/update.rst | 1 +
admin_manual/maintenance/upgrade.rst | 20 +++--
4 files changed, 120 insertions(+), 91 deletions(-)
diff --git a/admin_manual/configuration/occ_command.rst b/admin_manual/configuration/occ_command.rst
index c358e3b..3b75e0a 100644
--- a/admin_manual/configuration/occ_command.rst
+++ b/admin_manual/configuration/occ_command.rst
@@ -5,11 +5,9 @@ Using the occ Command
ownCloud's ``occ`` command (ownCloud console) is ownCloud's command-line
interface. You can perform many common server operations with ``occ``::
-* Maintenance tasks
* Manage apps
* Upgrade the ownCloud database
* Reset passwords, including administrator passwords
-* List files owned by users
* Convert the ownCloud database from SQLite to a more performant DB
* Query and change LDAP settings
@@ -21,7 +19,11 @@ all commands and options, like this example on Ubuntu::
$ sudo -u www-data php occ
This is the same as ``sudo -u www-data php occ list``.
-
+
+.. note:: See the **Setting Strong Directory Permissions** section of
+ :doc:`../installation/installation_wizard` to learn how to find your HTTP
+ user
+
Run it with the ``-h`` option for syntax help::
$ sudo -u www-data php occ -h
@@ -69,8 +71,8 @@ this example for the ``maintenance:mode`` command::
Maintenance Commands
--------------------
-These three maintenance commands put your ownCloud server into three modes: maintenance,
-singleuser, and repair.
+These three maintenance commands put your ownCloud server into
+maintenance and single-user mode, and run repair steps during updates.
You must put your ownCloud server into maintenance mode whenever you perform an
update or upgrade. This locks the sessions of all logged-in users, including
@@ -94,7 +96,9 @@ And turn it off when you're finished::
$ sudo -u www-data php occ maintenance:singleuser --off
Single user mode disabled
-TODO: What does maintenance:repair do? Needs details::
+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
+to::
$ sudo -u www-data php occ maintenance:repair
- Repair mime types
@@ -117,20 +121,22 @@ You can reset any user's password, including administrators (see
View a user's most recent login::
$ sudo -u www-data php occ user:lastseen layla
- layla`s last login: 09.01.2015 18:46
+ layla's last login: 09.01.2015 18:46
-TODO: does this count LDAP and other external users, or local only?::
+Generate a simple report that counts all users, including users on external user
+authentication servers such as LDAP::
$ sudo -u www-data php occ user:report
- +------------------+---+
- | User Report | |
- +------------------+---+
- | OC_User_Database | 2 |
- | | |
- | total users | 2 |
- | | |
- | user directories | 3 |
- +------------------+---+
+ +------------------+----+
+ | User Report | |
+ +------------------+----+
+ | Database | 12 |
+ | LDAP | 86 |
+ | | |
+ | total users | 98 |
+ | | |
+ | user directories | 2 |
+ +------------------+----+
Apps Commands
-------------
@@ -153,80 +159,84 @@ Disable an app::
Upgrade Command
---------------
-When you are performing an update or upgrade on your ownCloud server, it is
-better to use ``occ`` to perform the database upgrade step, rather than the Web
-GUI, in order to avoid timeouts.
-
-TODO: what timeouts? What causes them?
-
-You can perform a dry-run first to see what will happen, without changing
-anything::
-
- $ sudo -u www-data php occ upgrade --dry-run
-
-When this looks satisfactory, you can go ahead and perform the upgrade::
+When you are performing an update or upgrade on your ownCloud server (see the
+Maintenance section of this manual), it is better to use ``occ`` to perform the
+database upgrade step, rather than the Web GUI, in order to avoid timeouts. PHP
+scripts invoked from the Web interface are limited to 3600 seconds. In larger
+environments this may not be enough, leaving the system in an inconsistent
+state. Use this command to upgrade your databases::
$ sudo -u www-data php occ upgrade
-
-TODO why would you want to use --skip-migration-test? ::
-
- $ sudo -u www-data php occ upgrade --skip-migration-test
-
-File Scanning
--------------
+Before completing the upgrade, ownCloud first runs a simulation by
+copying all database tables to a temporary directory and then performing the
+upgrade on them, to ensure that the upgrade will complete correctly. This
+takes twice as much time, which on large installations can be many hours, so
+you can omit this step with the ``--skip-migration-test`` option::
-The ``files:scan`` command lists all files belonging to a specified user, and
-all files that belong to all users. This lists all files that belong to user
-layla::
+ $ sudo -u www-data php occ upgrade --skip-migration-test
- $ sudo -u www-data php occ files:scan layla
+You can perform this simulation manually with the ``--dry-run`` option::
+
+ $ sudo -u www-data php occ upgrade --dry-run
-This lists all files owned by all of your ownCloud users::
-
- $ sudo -u www-data php occ files:scan --all
-
-You can store all those filenames in a text file. The file must be created in a
-directory that you have write permissions to, such as your home directory::
-
- $ sudo -u www-data php occ files:scan layla --all > /home/user/ocfilelist.txt
-
Database Conversion
-------------------
The SQLite database is good for testing, and for ownCloud servers with small
-workloads, but servers with more than a few users and data files should use
-MariaDB, MySQL, PostgreSQL, or Oracle. You can use ``occ`` to convert from
-SQLite to one of these other databases. You need:
+workloads, but production servers with multiple users should use MariaDB, MySQL,
+or PostgreSQL. You can use ``occ`` to convert from SQLite to one of these other
+databases. You need:
* Your desired database installed and its PHP connector
* The login and password of a database admin user
* The database port number, if it is a non-standard port
-This is example converts to MariaDB, and also converts the schema for all
-installed apps::
+This is example converts to MySQL/MariaDB::
$ sudo -u www-data php occ db:generate-change-script
- $ sudo -u www-data php occ db:convert-type --all-apps mysql oc_dbuser 127.0.0.1 oc_database
+ $ sudo -u www-data php occ db:convert-type mysql oc_dbuser 127.0.0.1
+ oc_database
For a more detailed explanation see :doc:`../maintenance/convert_db`
LDAP Commands
-------------
-TODO: explanation of each LDAP command, and example command output
+You can run the following LDAP commands with ``occ``.
-These all do something::
+Search for an LDAP user, using this syntax::
- $ sudo -u www-data php occ ldap:search
- $ sudo -u www-data php occ ldap:set-config
- $ sudo -u www-data php occ ldap:show-config
- $ sudo -u www-data php occ ldap:test-config
+ $ sudo -u www-data php occ ldap:search [--group] [--offset="..."]
+ [--limit="..."] search
+
+This example searches for usernames that includes "rob"::
+ $ sudo -u www-data php occ ldap:search rob
+You can see your whole LDAP configuration, or the configuration for a single
+configID::
+ $ sudo -u www-data php occ ldap:show-config
+ $ sudo -u www-data php occ ldap:show-config s01
+
+The ``ldap:set-config`` command is for manipulating configurations, like this
+example that sets search attributes::
+ $ sudo -u www-data php occ ldap:set-config s01 ldapAttributesForUserSearch
+ "cn;givenname;sn;displayname;mail"
+
+``ldap:test-config`` tests whether your configuration is correct can bind to
+the server::
+
+ $ sudo -u www-data php occ ldap:test-config ""
+ The configuration is valid and the connection could be established!
+
+File Scanning
+-------------
+The ``files:scan`` command scans for new files for the file cache, and isn't
+intended to be run manually.
diff --git a/admin_manual/maintenance/convert_db.rst b/admin_manual/maintenance/convert_db.rst
index 2903336..b084529 100644
--- a/admin_manual/maintenance/convert_db.rst
+++ b/admin_manual/maintenance/convert_db.rst
@@ -1,49 +1,65 @@
-Converting Database Type
-========================
+=======================================================
+Converting From SQLite to MySQL, MariaDB, or PostgreSQL
+=======================================================
-You can convert a sqlite database to a more performing MySQL, MariaDB or PostgreSQL database with the ownCloud command line tool.
-Available since ownCloud version 7.0.0. To convert former ownCloud installations, first update to at least version 7.0.0.
+You can convert a SQLite database to a more performing MySQL, MariaDB or
+PostgreSQL database with the ownCloud command line tool ``occ``, which first
+appeared in ownCloud version 7.0.0. You must have ownCloud 7 to perform this
+conversion. SQLite is sufficient for testing and for very small installations,
+but for production servers with multiple users it is better to use MySQL,
+MariaDB or PostgreSQL.
+Please see :doc:`../configuration/occ_command` for more information on using
+the ``occ`` command.
-Run the conversion
-------------------
+Running the Conversion
+----------------------
-First setup the new database, here called "new_db_name".
-In ownCloud root folder call
+First set up the new database, in these examples called "new_db_name". In your
+ownCloud root folder call:
.. code-block:: bash
php occ db:convert-type [options] type username hostname database
-Available values for the ``type`` parameter are:
+The available values for the ``type`` parameter are:
* mysql (for MySQL or MariaDB)
-* oci (for Oracle)
* pgsql (for PostgreSQL)
-The Options
+Conversion Options
+------------------
-* ``--port="3306"`` the database port (optional)
-* ``--password="mysql_user_password"`` password for the new database. If omitted the tool will ask you (optional)
-* ``--clear-schema`` clear schema (optional)
-* ``--all-apps`` by default, tables for enabled apps are converted, use to convert also tables of deactivated apps (optional)
+* ``--port="3306"`` Your database port (optional, specify the port if it is a
+ non-standard port).
+* ``username`` A database admin user.
+* ``--password="mysql_user_password"`` The database admin password, if there is
+ one.
+* ``--clear-schema`` Clear the schema in the new DB (optional).
+* ``--all-apps`` By default, tables for enabled apps are converted. Use this
+ option to convert tables of deactivated apps.
-*Note:* The converter searches for apps in your configured app folders and uses the schema definitions in the apps to create the new table. So tables of removed apps will not be converted even with option ``--all-apps``
+.. note:: The converter searches for apps in your configured app folders and
+ uses the schema definitions in the apps to create the new table. So
+ the tables of removed apps will not be converted even with the option
+ ``--all-apps``
-For example
+This example converts the SQLite DB and tables for all installed apps to
+MySQL/MariaDB:
.. code-block:: bash
php occ db:convert-type --all-apps mysql oc_mysql_user 127.0.0.1 new_db_name
-To successfully proceed with the conversion, you must type ``yes`` when prompted with the question ``Continue with the conversion?``
-
-On success the converter will automatically configure the new database in your ownCloud config ``config.php``.
+To complete the conversion, type ``yes`` when prompted ``Continue with the
+conversion?`` On success the converter will automatically configure the new
+database in your ownCloud configuration in ``config.php``.
Unconvertible Tables
--------------------
-If you updated your ownCloud installation there might exist old tables, which are not used anymore. The converter will tell you
+After conversion some obsolete database tables may be left over. The converter
+will tell you what these are:
.. code-block:: bash
diff --git a/admin_manual/maintenance/update.rst b/admin_manual/maintenance/update.rst
index 021b286..0ec848b 100644
--- a/admin_manual/maintenance/update.rst
+++ b/admin_manual/maintenance/update.rst
@@ -1,3 +1,4 @@
+======================================
Updating ownCloud with the Updater App
======================================
diff --git a/admin_manual/maintenance/upgrade.rst b/admin_manual/maintenance/upgrade.rst
index 3deaa6b..07b2e9b 100644
--- a/admin_manual/maintenance/upgrade.rst
+++ b/admin_manual/maintenance/upgrade.rst
@@ -1,3 +1,4 @@
+==============================
Upgrading Your ownCloud Server
==============================
@@ -29,15 +30,10 @@ install all upgrades and updates in order.
Manual Upgrade Procedure
------------------------
-Start by putting your server in maintenance mode. There are two ways to do this.
-One by entering your ``config.php`` file and changing ``'maintenance' =>
-false,`` to ``'maintenance' => true,``. This prevents new logins, locks the
-sessions of logged-in users, and displays a status screen so users know what is
-happening. When you're finished upgrading, remember to change ``true`` to
-``false``.
-
-The second way is to use the ``occ`` command. This example is for
-Ubuntu Linux::
+Start by putting 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 ``occ`` command. This example is for Ubuntu Linux::
$ sudo -u www-data php occ maintenance:mode --on
@@ -47,6 +43,12 @@ When you're finished, take it out of maintenance mode. ::
Please see :doc:`../configuration/occ_command` to learn more about ``occ``.
+The other way is by entering your ``config.php`` file and changing
+``'maintenance' => false,`` to ``'maintenance' => true,``. When you're finished
+upgrading, remember to change ``true`` to ``false``.
+
+Then:
+
1. Ensure that you are running the latest point release of your current major
ownCloud version.
2. Deactivate all third party applications (not core apps), and review them for
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-owncloud/owncloud-doc.git
More information about the Pkg-owncloud-commits
mailing list