diff --git a/admin_manual/configuration/configuration_database.rst b/admin_manual/configuration/configuration_database.rst index ebb8df0c3..fdbe928dc 100644 --- a/admin_manual/configuration/configuration_database.rst +++ b/admin_manual/configuration/configuration_database.rst @@ -1,22 +1,34 @@ Database Configuration ====================== -ownCloud requires a database where administrative data will be held. Four different database types are currently -supported, `MySQL `_, `MariaDB `_, `SQLite `_, -and `PostgreSQL `_. MySQL or MariaDB are the recommended database engines. By default -SQLite is chosen because it is a file based database with the least administrative overhead. +ownCloud requires a database where administrative data will be held. Four +different database types are currently supported, +`MySQL `_ / `MariaDB `_, +`SQLite `_, `PostgreSQL `_ +and `Oracle `_. MySQL or MariaDB are the recommended +database engines. By default SQLite is chosen because it is a file based +database with the least administrative overhead. -.. note:: Because SQLite handles multiple users very badly SQLite is only recommended for single user ownCloud installations +.. note:: Because SQLite handles multiple users very badly SQLite is only + recommended for single user ownCloud installations. Requirements ------------ -If you decide to use MySQL, MariaDB, or PostgreSQL you need to install and set-up the -database first. These steps will not be covered by this description as they are easy to find elsewhere. +If you decide to use MySQL / MariaDB, PostgreSQL or Oracle, you need to install +and set up the server software first. These steps will not be covered by this +description as they are easy to find elsewhere. Parameters ---------- +.. note:: For setting up ownCloud to use any of these databases, use the + :doc:`../installation/installation_wizard`. + You usually don't need to edit the respective values in the + :file:`config/config.php`, just in special cases e.g. if you want to + connect your ownCloud instance to a database created by a previous + installation of ownCloud. + MySQL/MariaDB Database ~~~~~~~~~~~~~~~~~~~~~~ @@ -69,8 +81,11 @@ You can quit the prompt by entering:: quit -In the ownCloud configuration you need to set the hostname on which the -database is running and a valid username and password to access it. +An ownCloud configured with MySQL would contain the hostname on which the +database is running, a valid username and 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: .. code-block:: php @@ -81,7 +96,7 @@ database is running and a valid username and password to access it. "dbuser" => "username", "dbpassword" => "password", "dbhost" => "localhost", - "dbtableprefix" => "", + "dbtableprefix" => "oc_", SQLite Database ~~~~~~~~~~~~~~~ @@ -99,10 +114,12 @@ It is not necessary to create a database and a database user in advance because this will automatically be done by ownCloud when you login for the first time. -In the ownCloud configuration in :file:`config/config.php` you need to set at least the **datadirectory** parameter to -the directory where your data and database should be stored. Note that for the PDO SQLite driver this directory must -be writable (this is recommended for ownCloud anyway). No authentication is required to access the database therefore -most of the default parameters could be taken as is: +An ownCloud configured to use sqlite only needs to contain the reference to a +writable data directory (which is required for the rest of ownCloud's operation +as well anyway). The :file:`config/config.php` as created by the +:doc:`installation/installation_wizard` could therefore contain entries like +this: + .. code-block:: php @@ -114,7 +131,7 @@ most of the default parameters could be taken as is: "dbpassword" => "", "dbhost" => "", "dbtableprefix" => "", - "datadirectory" => "/www/htdocs/owncloud/data", + "datadirectory" => "/var/www/html/owncloud/data", PostgreSQL Database ~~~~~~~~~~~~~~~~~~~ @@ -158,10 +175,11 @@ You can quit the prompt by entering:: \q -In the ownCloud configuration you need to set the hostname on which the -database is running and a valid username (and sometimes a password) to -access it. If the database has been installed on the same server as -ownCloud a password is very often not required to access the database. +An ownCloud configured with PostgreSQL would contain the hostname on which the +database is running, a valid username and 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: .. code-block:: php @@ -172,7 +190,7 @@ ownCloud a password is very often not required to access the database. "dbuser" => "username", "dbpassword" => "password", "dbhost" => "localhost", - "dbtableprefix" => "", + "dbtableprefix" => "oc_", Oracle Database ~~~~~~~~~~~~~~~ @@ -231,10 +249,11 @@ You can quit the prompt by entering:: exit -In the ownCloud configuration you need to set the hostname on which the -database is running and a valid username and password to -access it. If the database has been installed on the same server as -ownCloud to config file could look like this: +An ownCloud configured with Oracle would contain the hostname on which the +database is running, a valid username and 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: .. code-block:: php @@ -246,17 +265,18 @@ ownCloud to config file could look like this: "dbpassword" => "password", "dbhost" => "localhost", -.. note:: This example assumes you are running an Oracle Express Edition on ``localhost``. - The ``dbname`` is the name of the Oracle instance. For Oracle Express Edition it - is always ``XE``. +.. note:: This example assumes you are running an Oracle Express Edition on + ``localhost``. The ``dbname`` is the name of the Oracle instance. + For Oracle Express Edition it is always ``XE``. Troubleshooting --------------- -How can I find out if my MySQL/PostgreSQL server is reachable? +How can I find out if my MySQL/PostgreSQL server is reachable? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the ping command to check the server availability:: +To check the server's network availability, use the ping command on +the server's host name (db.server.com in this example):: ping db.server.dom @@ -267,6 +287,9 @@ Use the ping command to check the server availability:: 64 bytes from your-server.local.lan (192.168.1.10): icmp_req=2 ttl=64 time=0.055 ms 64 bytes from your-server.local.lan (192.168.1.10): icmp_req=3 ttl=64 time=0.062 ms +For a more detailed check whether the access to the database server software +itself works correctly, see the next question. + How can I find out if a created user can access a database? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -285,8 +308,16 @@ command line interface: **MySQL**:: +Assuming the database server is installed on the same sytem you're running, +the command from, use: + mysql -uUSERNAME -p +To acess a MySQL installation on a different machine, add the -h option with +the respective host name: + + mysql -uUSERNAME -p -h HOSTNAME + :: mysql> SHOW VARIABLES LIKE "version"; @@ -300,8 +331,16 @@ command line interface: **PostgreSQL**:: +Assuming the database server is installed on the same sytem you're running +the command from, use: + psql -Uusername -downcloud +To acess a MySQL installation on a different machine, add the -h option with +the respective host name: + + psql -Uusername -downcloud -h HOSTNAME + :: postgres=# SELECT version(); @@ -311,6 +350,8 @@ command line interface: **Oracle**:: +On the machine where your Oracle database is installed, type + sqlplus username :: diff --git a/admin_manual/installation/images/install-wizard-advanced.png b/admin_manual/installation/images/install-wizard-advanced.png new file mode 100644 index 000000000..61572477e Binary files /dev/null and b/admin_manual/installation/images/install-wizard-advanced.png differ diff --git a/admin_manual/installation/images/install-wizard.png b/admin_manual/installation/images/install-wizard.png new file mode 100644 index 000000000..be77cce4a Binary files /dev/null and b/admin_manual/installation/images/install-wizard.png differ diff --git a/admin_manual/installation/installation_linux.rst b/admin_manual/installation/installation_linux.rst index b326004ca..e97205ac4 100644 --- a/admin_manual/installation/installation_linux.rst +++ b/admin_manual/installation/installation_linux.rst @@ -30,4 +30,5 @@ or else the installation process might fail. Follow the wizard to complete your installation *********************************************** -For setting up your ownCloud instance after installation, please refer to the :ref:`install-wizard` section. +For setting up your ownCloud instance after installation, please refer to the +:doc:`installation_wizard` section. diff --git a/admin_manual/installation/installation_source.rst b/admin_manual/installation/installation_source.rst index 1597cb18e..d79af6603 100644 --- a/admin_manual/installation/installation_source.rst +++ b/admin_manual/installation/installation_source.rst @@ -582,81 +582,28 @@ Microsoft Internet Information Server (IIS) See :doc:`installation_windows` for further instructions. -.. _install-wizard: - -Follow the Install Wizard +Install Wizard ~~~~~~~~~~~~~~~~~~~~~~~~~ -* Open your web browser -* Navigate to your ownCloud instance. +The last thing to do is to click through the installation wizard. - * If you are installing ownCloud on the same machine as you are accessing the - install wizard from, the URL will be https://localhost/owncloud - * If you are installing ownCloud on a different machine, you'll have to access - it by its hostname or IP address, e.g. https://example.com/owncloud - * If you are using a self-signed certificate, you will be presented with a - security warning about the issuer of the certificate not being trusted which - you can ignore. +Here are some guidelines for the values to enter there if following the +Ubuntu-Apache-MySQL walk-through: -* You will be presented with the setup screen -* Enter username and password for the administrative user account -* Expand Advanced options to choose a data folder and the database system +* Make sure to click the "Advanced" Button to see the database settings -* If you are not using Apache as the web server, please set the data directory - to a location outside of the document root. +* Choose MySQL as Database backend (you might not be presented with any other +choice if you haven't installed any other database systems). +* As Database host, enter ``localhost``. +* As Database user enter ``root``. +* As Database password, enter the password you entered during installation of +the MySQL server package. +* As Database name, enter an arbitrary name as you see fit -* If following the Ubuntu-Apache-MySQL walk-through: - - * choose MySQL as Database backend (you might not be presented with any other - choice if you haven't installed any other database systems). - * As Database host, enter ``localhost``. - * As Database user enter ``root``. - * As Database password, enter the password you entered during installation of - the MySQL server package. - * As Database name, enter an arbitrary name as you see fit - - * Beware that there are restrictions as to what characters a database name - may or may not contain, see the - `MySQL Schema Object Names documentation`_ for details); - * Make sure to choose a name under which no database exists yet - * ownCloud will use the provided credentials and create its own user with - permissions only on its own database. - -* In general, you have the following choices regarding the database: - - * For basic installs we recommend SQLite as it is easy to setup (ownCloud will do - it for you). The performance when using sqlite is however inferior to the two - other options. - * For larger installs you should use MySQL or PostgreSQL. - * Note that you will only be able to choose among the php database connectors - which are actually installed on the system (see package requirements above). - * Further, it is not easily possible to migrate to another database system - once you have set up your ownCloud to use a specific one. So make sure to - carefully consider which database system to use. - * When using MySQL or PostgreSQL you have two options regarding the database - name and user account you specify: - - * You can specify either an admin/root user, and the name of a database - which does not yet exist. This lets ownCloud create its own database; it - will also create a database user account with restricted rights (with the - same username as you specified for the administrative user, plus an - ``oc_`` prefix) and will use that for all subsequent database access. - * You can enter the name of an existing database and the username/password - of a user with restricted permissions - - * You can create such a user yourself e.g. via phpmyadmin. - * This user shouldn't have permission to create a database. - * It should have full permissions on the (existing) database with the - name you specify. - -* Press "Finish Setup" -* ownCloud will set up your cloud according to the given settings -* When its finished, it will log you in as administrative user and present the - "Welcome to ownCloud" screen. +Continue by following the :doc:`installation_wizard`. .. _PHP PPA: https://launchpad.net/~ondrej/+archive/php5 .. _ownCloud Installation Page: http://owncloud.org/install .. _options for free SSL certificates: https://www.sslshopper.com/article-free-ssl-certificates-from-a-free-certificate-authority.html .. _github gist for further instructions: https://gist.github.com/2200407 .. _Nginx HTTP SSL Module documentation: http://wiki.nginx.org/HttpSslModule -.. _MySQL Schema Object Names documentation: http://dev.mysql.com/doc/refman/5.5/en/identifiers.html diff --git a/admin_manual/installation/installation_windows.rst b/admin_manual/installation/installation_windows.rst index d6271154a..ccc151e81 100644 --- a/admin_manual/installation/installation_windows.rst +++ b/admin_manual/installation/installation_windows.rst @@ -155,7 +155,7 @@ This part installs MySQL on your Windows machine. #. Select the modify security settings box on the next page, and enter a password you will remember. You will need this password when you configure ownCloud. -#. Uncheck **enable** root access from remote machines” for security reasons. +#. Uncheck “enable root access from remote machines” for security reasons. #. Click execute, and wait while the instance is created and launched. #. Click Finish when this is all complete. @@ -196,20 +196,11 @@ Installing ownCloud button “to change permissions, click edit”. 6. Select the “users” user from the list, and check the box “write”. 7. Apply these settings and close out. -8. Now open your browser and go to http://localhost/owncloud (or localhost if it - is installed in the root www directory). This should bring up the ownCloud - configuration page. -9. At this page, you enter your desired ownCloud user name and password for the - administrator, and expand the little arrow. -10. Select MySQL as the database, and enter your MySQL database user name, - password and desired instance name – use the user name and password you setup - for MySQL earlier in step 3, and pick any name for the database instance. -.. note:: The ownCloud admin password and the MySQL password CANNOT be the same - in any way. - -11. Click next, and ownCloud should have you logged in as the admin user, and - you can get started exploring ownCloud, creating other users and more! +Continue by following the :doc:`installation_wizard`. +Select MySQL as the database, and enter your MySQL database user name, +password and desired instance name – use the user name and password you setup +during MySQL installation, and pick any name for the database instance. Ensure Proper HTTP-Verb handling ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/admin_manual/installation/installation_wizard.rst b/admin_manual/installation/installation_wizard.rst new file mode 100644 index 000000000..337873ea0 --- /dev/null +++ b/admin_manual/installation/installation_wizard.rst @@ -0,0 +1,115 @@ +Installation Wizard +------------------- + +When ownCloud prerequisites are fulfilled and all ownCloud files are installed +on the server, the last thing left to do for finishing the installation is +running the Installation Wizard. + +* Open your web browser +* Navigate to your ownCloud instance. + + * If you are installing ownCloud on the same machine as you are accessing the + install wizard from, the url will be https://localhost/owncloud + * If you are installing ownCloud on a different machine, you'll have to access + it by its hostname or IP address, e.g. https://example.com/owncloud + * If you are using a self-signed certificate, you will be presented with a + security warning about the issuer of the certificate not being trusted which + you can ignore. + +* You will be presented with the setup screen: + +.. image:: images/install-wizard.png + +Required Settings +~~~~~~~~~~~~~~~~~ +Under "create an admin account" you are requested to enter a username and +password for the administrative user account. You can choose any username and +password as you see fit, just make sure to remember it, you will need it later +whenever you want to configure something for your ownCloud instance. + +Advanced Options +~~~~~~~~~~~~~~~~ + +* Advanced settings are available for configuring a different database or data + directory than the default ones. + +* If you are not using Apache as the web server, it is highly + recommended to configure the data directory to a location outside of + the document root. Otherwise all user data is potentially publicly + visible! + +* Show these additional options by clicking on "Advanced": + +.. image:: images/install-wizard-advanced.png + +Database choice +*************** + +* For a guideline on which database system to choose, and on pointers how to + set them up for being available for php/ownCloud, see + :doc:`../configuration/configuration_database` + +* Note that you will only be able to choose among the php database connectors + which are actually installed on the system. + +* It is not easily possible to migrate to another database system once you have + set up your ownCloud to use a specific one. So make sure to carefully + consider which database system to use. + +* When using MySQL or PostgreSQL you have two options regarding the database + name and user account you specify: + + * You can specify either an admin/root user, and the name of a database + which does not yet exist. This lets ownCloud create its own database; it + will also create a database user account with restricted rights (with the + same username as you specified for the administrative user, plus an + ``oc_`` prefix) and will use that for all subsequent database access. + + * Beware that there are restrictions as to what characters a database name + may or may not contain, see the + `MySQL Schema Object Names documentation`_ for details); + * Make sure to choose a name under which no database exists yet + * ownCloud will use the provided credentials and create its own user with + permissions only on its own database. + + * You can enter the name of an existing database and the username/password + of a user with permissions restricted to this one database only + + * You can create such a user yourself, e.g. via phpmyadmin. + * This user shouldn't have permission to create a database. + * It should have full permissions on the (existing) database with the + name you specify. + + +Finish Installation +~~~~~~~~~~~~~~~~~~~ +* Once you've entered all settings, press "Finish Setup" +* ownCloud will set up your cloud according to the given settings +* When its finished, it will log you in as administrative user and present the + "Welcome to ownCloud" screen. + + +Note +~~~~ +ownCloud will take the URL used to access the Installation Wizard and insert +that into the config.php file for the ‘trusted_domains’ setting. + +Users will only be able to log into ownCloud when they are using a domain name +listed in the ‘trusted_domans’ setting. + +In the event that a load balancer is in place, there will be no issues, as long +as it sends the correct X-Forwarded-Host header. + +It should be noted that the loopback address, 127.0.0.1, is whitelisted and +therefore users on the ownCloud server who access ownCloud with the loopback +will successfully login. In the event that an improper URL is used, the +following error will appear: + +.. image:: images/untrusted-domain.png + +For configuration examples, refer to the :file:`config/config.sample.php` +document. + + + +.. _MySQL Schema Object Names documentation: http://dev.mysql.com/doc/refman/5.5/en/identifiers.html