[Pkg-owncloud-commits] [owncloud-doc] 67/110: New manual page documenting occ commands
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 d0d9c5196538c99df25f837e26b6e956e68d1e73
Author: Carla Schroder <carla at owncloud.com>
Date: Mon Jan 12 11:40:41 2015 -0800
New manual page documenting occ commands
---
admin_manual/configuration/index.rst | 1 +
admin_manual/configuration/occ_command.rst | 252 +++++++++++++++++++++
.../configuration/reset_admin_password.rst | 2 +-
admin_manual/maintenance/enable_maintenance.rst | 24 +-
admin_manual/maintenance/update.rst | 15 +-
admin_manual/maintenance/upgrade.rst | 36 ++-
6 files changed, 302 insertions(+), 28 deletions(-)
diff --git a/admin_manual/configuration/index.rst b/admin_manual/configuration/index.rst
index 6638169..8435b39 100644
--- a/admin_manual/configuration/index.rst
+++ b/admin_manual/configuration/index.rst
@@ -23,6 +23,7 @@ Configuration
knowledgebase_configuration
language_configuration
logging_configuration
+ occ_command
previews_configuration
reverse_proxy_configuration
search_configuration
diff --git a/admin_manual/configuration/occ_command.rst b/admin_manual/configuration/occ_command.rst
new file mode 100644
index 0000000..c358e3b
--- /dev/null
+++ b/admin_manual/configuration/occ_command.rst
@@ -0,0 +1,252 @@
+=====================
+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
+
+``occ`` is in the :file:`owncloud/` directory; for example
+:file:`/var/www/owncloud` on Ubuntu Linux. ``occ`` is a PHP script. The
+preferred way to run it is as your HTTP user. Running it with no options lists
+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``.
+
+Run it with the ``-h`` option for syntax help::
+
+ $ sudo -u www-data php occ -h
+
+Display your ownCloud version::
+
+ $ sudo -u www-data php occ -V
+ ownCloud version 7.0.4
+
+Query your ownCloud server status::
+
+ $ sudo -u www-data php occ status
+ Array
+ (
+ [installed] => true
+ [version] => 7.0.4.2
+ [versionstring] => 7.0.4
+ [edition] =>
+ )
+
+``occ`` has options, commands, and arguments. Options and arguments are
+optional, while commands are required. The syntax is::
+
+ occ [options] command [arguments]
+
+Get detailed information on individual commands with the ``help`` command, like
+this example for the ``maintenance:mode`` command::
+
+ $ sudo -u www-data php occ help maintenance:mode
+ Usage:
+ maintenance:mode [--on] [--off]
+
+ Options:
+ --on enable maintenance mode
+ --off disable maintenance mode
+ --help (-h) Display this help message.
+ --quiet (-q) Do not output any message.
+ --verbose (-v|vv|vvv) Increase the verbosity of messages: 1 for normal
+ output, 2 for more verbose output and 3 for debug
+ --version (-V) Display this application version.
+ --ansi Force ANSI output.
+ --no-ansi Disable ANSI output.
+ --no-interaction (-n) Do not ask any interactive question.
+
+Maintenance Commands
+--------------------
+
+These three maintenance commands put your ownCloud server into three modes: maintenance,
+singleuser, and repair.
+
+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
+administrators, and displays a status screen warning that the server is in
+maintenance mode. Users who are not already logged in cannot log in until
+maintenance mode is turned off. When you take the server out of maintenance mode
+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 ownCloud 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
+
+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::
+
+ $ sudo -u www-data php occ maintenance:repair
+ - Repair mime types
+ - Repair config
+
+User Commands
+-------------
+
+The ``user`` commands reset passwords, display a simple report showing how
+many users you have, and when a user was last logged in.
+
+You can reset any user's password, including administrators (see
+:doc:`reset_admin_password`). In this example the username is layla::
+
+ $ sudo -u www-data php occ user:resetpassword layla
+ Enter a new password:
+ Confirm the new password:
+ Successfully reset password for layla
+
+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
+
+TODO: does this count LDAP and other external users, or local only?::
+
+ $ sudo -u www-data php occ user:report
+ +------------------+---+
+ | User Report | |
+ +------------------+---+
+ | OC_User_Database | 2 |
+ | | |
+ | total users | 2 |
+ | | |
+ | user directories | 3 |
+ +------------------+---+
+
+Apps Commands
+-------------
+
+The ``app`` commands list, enable, and disable apps. This lists all of your
+installed apps, and shows whether they are enabled or disabled::
+
+ $ sudo -u www-data php occ app:list
+
+Enable an app::
+
+ $ sudo -u www-data php occ app:enable external
+ external enabled
+
+Disable an app::
+
+ $ sudo -u www-data php occ app:disable external
+ external disabled
+
+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::
+
+ $ 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
+-------------
+
+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 files:scan layla
+
+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:
+
+* 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::
+
+ $ 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
+
+For a more detailed explanation see :doc:`../maintenance/convert_db`
+
+LDAP Commands
+-------------
+
+TODO: explanation of each LDAP command, and example command output
+
+These all do something::
+
+ $ 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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/admin_manual/configuration/reset_admin_password.rst b/admin_manual/configuration/reset_admin_password.rst
index c4ac912..01099e4 100644
--- a/admin_manual/configuration/reset_admin_password.rst
+++ b/admin_manual/configuration/reset_admin_password.rst
@@ -17,7 +17,7 @@ example ``/var/www/owncloud/occ``. ``occ`` has a command for resetting all
user passwords, ``user:resetpassword``. It is best to run ``occ`` as the HTTP
user, as in this example::
- $ sudo -u www-data /var/www/owncloud/occ user:resetpassword admin
+ $ sudo -u www-data php /var/www/owncloud/occ user:resetpassword admin
Enter a new password:
Confirm the new password:
Successfully reset password for admin
diff --git a/admin_manual/maintenance/enable_maintenance.rst b/admin_manual/maintenance/enable_maintenance.rst
index 7d4ff82..6153410 100644
--- a/admin_manual/maintenance/enable_maintenance.rst
+++ b/admin_manual/maintenance/enable_maintenance.rst
@@ -1,21 +1,21 @@
Maintenance Mode Configuration
==============================
-If you want to prevent users to login to ownCloud before you start doing
-some maintenance work, you need to set the value of the **maintenance**
-parameter to *true*. Please keep in mind that users who are already logged-in
-are kicked out of ownCloud instantly.
+You must put your ownCloud server into maintenance mode before performing
+updates or upgrades, and for performing troubleshooting and maintenance. Please
+see :doc:`../configuration/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.
-
-
-
-Parameters
-----------
+``maintenance:mode`` locks the sessions of logged-in users and prevents new
+logins. This is the mode to use for updates and upgrades. You may also put your
+server into this mode by editing :file:`config/config.php`. Change
+``"maintenance" => false`` to ``"maintenance" => true``:
.. code-block:: php
- <?php
+ <?php
- "maintenance" => false,
+ "maintenance" => true,
-This parameters can be set in the :file:`config/config.php`
+Then change it back to ``false`` when you are finished.
\ No newline at end of file
diff --git a/admin_manual/maintenance/update.rst b/admin_manual/maintenance/update.rst
index 84717dc..021b286 100644
--- a/admin_manual/maintenance/update.rst
+++ b/admin_manual/maintenance/update.rst
@@ -56,7 +56,9 @@ steps:
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 ownCloud
- directory; see the
+ directory; see the **Setting Strong Directory Permissions** section of
+ :doc:`../installation/installation_wizard` to learn about managing directory
+ permissions for your ownCloud server.
4. Navigate to your 'Admin' page and click the 'Update Center' button under
Updater:
@@ -68,9 +70,10 @@ steps:
.. figure:: ../images/updater-3.png
6. Click Update, and carefully read the messages. If there are any problems it
-will tell you. The most common issue is directory permissions; see
-:ref:`setting_strong_permissions`. Otherwise you will see a message about
-checking your installation, making a backup, and moving files:
+ will tell you. The most common issue is directory permissions; see the
+ **Setting Strong Directory Permissions** section of
+ :doc:`../installation/installation_wizard`. Otherwise you will see a message
+ about checking your installation, making a backup, and moving files:
.. figure:: ../images/updater-4.png
@@ -92,9 +95,7 @@ checking your installation, making a backup, and moving files:
Refresh your Admin page to verify your new version number.
If the Updater app fails, then you must update manually. See :doc:`upgrade` to
-learn how to upgrade manually.
-
-.. _setting_strong_permissions:
+learn how to upgrade manually.
Setting Strong Permissions
--------------------------
diff --git a/admin_manual/maintenance/upgrade.rst b/admin_manual/maintenance/upgrade.rst
index 6b54e04..3deaa6b 100644
--- a/admin_manual/maintenance/upgrade.rst
+++ b/admin_manual/maintenance/upgrade.rst
@@ -18,15 +18,34 @@ unsupported, and you'll likely experience unpredictable results. It is best to
install all upgrades and updates in order.
.. note:: If you installed ownCloud from
- `openSUSE Build Service <http://software.opensuse.org/download.html?project=isv:ownCloud:community&package=owncloud>`_, or from your Linux distribution repositories using your package manager, then it is best to update/upgrade ownCloud using your package manager rather than using the Updater app or upgrading manually. You should still maintain regular backups (see :doc:`backup`), and make a backup before every update/upgrade.
+ `openSUSE Build Service
+ <http://software.opensuse.org/download.html?project=isv:ownCloud:community&
+ package=owncloud>`_, or from your Linux distribution repositories using
+ your package manager, then it is best to update/upgrade ownCloud using your
+ package manager rather than using the Updater app or upgrading manually.
+ You should still maintain regular backups (see :doc:`backup`), and make a
+ backup before every update/upgrade.
Manual Upgrade Procedure
------------------------
-Start by putting your server in maintenance mode. Do this by entering your
-``config.php`` file and changing ``'maintenance' => false,`` to ``'maintenance'
-=> true,``. This prevents new logins, and logged-in users can't make any
-further requests.
+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::
+
+ $ sudo -u www-data php occ maintenance:mode --on
+
+When you're finished, take it out of maintenance mode. ::
+
+ $ sudo -u www-data php occ maintenance:mode --off
+
+Please see :doc:`../configuration/occ_command` to learn more about ``occ``.
1. Ensure that you are running the latest point release of your current major
ownCloud version.
@@ -179,10 +198,11 @@ To start the Windows IIS web server, you can use either the user interface
If you are an enterprise customer, or are running a large installation with
a lot of files and users, you should launch the update from the command
- line. The ``occ`` command is in your ``owncloud/`` directory, so on a
- typical Linux installation you could run this command:
+ line using ``occ`` to avoid timeouts, like this example on Ubuntu Linux::
- ``php /var/www/owncloud/occ upgrade``
+ $ sudo -u www-data php occ upgrade
+
+ Please see :doc:`../configuration/occ_command` to learn more about ``occ``.
13. The upgrade operation takes a few minutes, depending on the size of your
installation. When it is finished you will see a success message, or an
--
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