From bd205c58c7ce69666fd02a14b73287ba3ae048ab Mon Sep 17 00:00:00 2001 From: Morris Jobke Date: Wed, 8 Oct 2014 23:01:46 +0200 Subject: [PATCH] apply @carlaschroder's changes from owncloud/documentation#594 --- config/config.sample.php | 379 ++++++++++++++++++++++----------------- 1 file changed, 215 insertions(+), 164 deletions(-) diff --git a/config/config.sample.php b/config/config.sample.php index 21e73a1df62..c4261dd2b6a 100755 --- a/config/config.sample.php +++ b/config/config.sample.php @@ -16,6 +16,7 @@ * also to this line * * everything between the ` *\/` and the next `/**` will be treated as the * config option + * * use RST syntax */ /** @@ -42,56 +43,74 @@ $CONFIG = array( 'instanceid' => '', /** - * Define the salt used to hash the user passwords. All your user passwords are - * lost if you lose this string. + * The salt used to hash all passwords, auto-generated by the ownCloud + * installer. (There are also per-user salts.) If you lose this salt you lose + * all your passwords. */ 'passwordsalt' => '', /** - * List of trusted domains, to prevent host header poisoning ownCloud is only - * using these Host headers + * Your list of trusted domains that users can log into. Specifying trusted + * domains prevents host header poisoning. Do not remove this, as it performs + * necessary security checks. */ 'trusted_domains' => array('demo.example.org', 'otherdomain.example.org:8080'), /** - * The directory where the user data is stored, default to data in the ownCloud - * directory. The sqlite database is also stored here, when sqlite is used. + * Where user files are stored; this defaults to ``data/`` in the ownCloud + * directory. The SQLite database is also stored here, when you use SQLite. */ 'datadirectory' => '', /** - * Type of database, can be sqlite, mysql or pgsql + * The current version number of your ownCloud installation. This is set up + * during installation and update, so you shouldn't need to change it. + */ +'version' => '', + +/** + * Identifies the database used with this installation: ``sqlite``, ``mysql``, + * ``pgsql``, ``oci``, or ``mssql``. */ 'dbtype' => 'sqlite', /** - * Host running the ownCloud database. To specify a port use 'HOSTNAME:####'; to - * specify a unix sockets use 'localhost:/path/to/socket'. + * Your host server name, for example ``localhost``, ``hostname``, + * ``hostname.example.com``, or the IP address. To specify a port use + * ``hostname:####``; to specify a Unix socket use + * ``localhost:/path/to/socket``. */ 'dbhost' => '', /** - * Name of the ownCloud database + * The name of the ownCloud database for your installation. The default name is + * ``owncloud``, and you may give it any arbitrary name at installation when + * your database is MySQL, MariaDB, or PostgreSQL. */ 'dbname' => 'owncloud', /** - * User to access the ownCloud database + * The user that ownCloud uses to write to the database. This must be unique + * across ownCloud instances using the same SQL database. This is set up during + * installation, so you shouldn't need to change it. */ 'dbuser' => '', /** - * Password to access the ownCloud database + * The password for the database user. This is set up during installation, so + * you shouldn't need to change it. */ 'dbpassword' => '', /** - * Prefix for the ownCloud tables in the database + * Prefix for the ownCloud tables in the database. */ 'dbtableprefix' => '', /** - * Flag to indicate ownCloud is successfully installed (true = installed) + * Indicates whether the ownCloud instance was installed successfully; ``true`` + * indicates a successful installation, and ``false`` indicates an unsuccessful + * installation. */ 'installed' => false, @@ -104,51 +123,57 @@ $CONFIG = array( */ /** - * Optional ownCloud default language - overrides automatic language detection - * on public pages like login or shared items. This has no effect on the user's - * language preference configured under 'personal -> language' once they have - * logged in + * This sets the default language on your ownCloud server, using ISO_639-1 + * language codes such as ``en`` for English, ``de`` for German, and ``fr`` for + * French. It overrides automatic language detection on public pages like login + * or shared items. User's language preferences configured under "personal -> + * language" override this setting after they have logged in. */ 'default_language' => 'en', /** - * Default app to open on login. - * - * This can be a comma-separated list of app ids. If the first app is not - * enabled for the current user, it will try with the second one and so on. If - * no enabled app could be found, the 'files' app will be displayed instead. + * Set the default app to open on login. Use the app names as they appear in the + * URL after clicking them in the Apps menu, such as documents, calendar, and + * gallery. You can use a comma-separated list of app names, so if the first + * app is not enabled for a user then ownCloud will try the second one, and so + * on. If no enabled apps are found it defaults to the Files app. */ 'defaultapp' => 'files', /** - * Enable the help menu item in the settings + * ``true`` enables the Help menu item in the user menu (top left of the + * ownCloud Web interface). ``false`` removes the Help item. */ 'knowledgebaseenabled' => true, /** - * Specifies whether avatars should be enabled + * ``true`` enables avatars, or user profile photos. These appear on the User + * page and on user's Personal pages. ``false`` disables them. */ 'enable_avatars' => true, /** - * Allow user to change his display name, if it is supported by the back-end + * ``true`` allows users to change their display names (on their Personal + * pages), and ``false`` prevents them from changing their display names. */ 'allow_user_to_change_display_name' => true, /** - * Lifetime of the remember login cookie, default is 15 days + * Lifetime of the remember login cookie, which is set when the user clicks the + * ``remember`` checkbox on the login screen. The default is 15 days, expressed + * in seconds. */ 'remember_login_cookie_lifetime' => 60*60*24*15, /** - * Life time of a session after inactivity + * The lifetime of a session after inactivity; the default is 24 hours, + * expressed in seconds. */ 'session_lifetime' => 60 * 60 * 24, /** - * Enable/disable session keep alive when a user is logged in in the Web UI. - * This is achieved by sending a 'heartbeat' to the server to prevent the - * session timing out. + * Enable or disable session keep-alive when a user is logged in to the Web UI. + * Enabling this sends a "heartbeat" to the server to keep it from timing out. */ 'session_keepalive' => true, @@ -160,7 +185,9 @@ $CONFIG = array( 'skeletondirectory' => '', /** - * TODO + * The ``user_backends`` app allows you to configure alternate authentication + * backends. Supported backends are IMAP (OC_User_IMAP), SMB (OC_User_SMB), and + * FTP (OC_User_FTP). */ 'user_backends' => array( array( @@ -178,72 +205,88 @@ $CONFIG = array( */ /** - * Domain name used by ownCloud for the sender mail address, e.g. - * no-reply@example.com + * The return address that you want to appear on emails sent by the ownCloud + * server, for example ``oc-admin@example.com``, substituting your own domain, + * of course. */ 'mail_domain' => 'example.com', /** - * FROM address used by ownCloud for the sender mail address, e.g. - * owncloud@example.com - * - * This setting overwrites the built in 'sharing-noreply' and - * 'lostpassword-noreply' FROM addresses, that ownCloud uses + * FROM address that overrides the built-in ``sharing-noreply`` and + * ``lostpassword-noreply`` FROM addresses. */ 'mail_from_address' => 'owncloud', /** - * Enable SMTP class debugging + * Enable SMTP class debugging. */ 'mail_smtpdebug' => false, /** - * Mode to use for sending mail, can be sendmail, smtp, qmail or php, see - * PHPMailer docs + * Which mode to use for sending mail: ``sendmail``, ``smtp``, ``qmail`` or + * ``php``. + * + * If you are using local or remote SMTP, set this to ``smtp``. + * + * If you are using PHP mail you must have an installed and working email system + * on the server. The program used to send email is defined in the ``php.ini`` + * file. + * + * For the ``sendmail`` option you need an installed and working email system on + * the server, with ``/usr/sbin/sendmail`` installed on your Unix system. + * + * For ``qmail`` the binary is /var/qmail/bin/sendmail, and it must be installed + * on your Unix system. */ 'mail_smtpmode' => 'sendmail', /** - * Host to use for sending mail, depends on mail_smtpmode if this is used + * This depends on ``mail_smtpmode``. Specified the IP address of your mail + * server host. This may contain multiple hosts separated by a semi-colon. If + * you need to specify the port number append it to the IP address separated by + * a colon, like this: ``127.0.0.1:24``. */ 'mail_smtphost' => '127.0.0.1', /** - * Port to use for sending mail, depends on mail_smtpmode if this is used + * This depends on ``mail_smtpmode``. Specify the port for sending mail. */ 'mail_smtpport' => 25, /** - * SMTP server timeout in seconds for sending mail, depends on mail_smtpmode if - * this is used + * This depends on ``mail_smtpmode``. This set an SMTP server timeout, in + * seconds. You may need to increase this if you are running an anti-malware or + * spam scanner. */ 'mail_smtptimeout' => 10, /** - * SMTP connection prefix or sending mail, depends on mail_smtpmode if this is - * used. Can be '', 'ssl' or 'tls' + * This depends on ``mail_smtpmode``. Specify when you are using ``ssl`` or + * ``tls``, or leave empty for no encryption. */ 'mail_smtpsecure' => '', /** - * Authentication needed to send mail, depends on mail_smtpmode if this is used - * (false = disable authentication) + * This depends on ``mail_smtpmode``. Change this to ``true`` if your mail + * server requires authentication. */ 'mail_smtpauth' => false, /** - * Authentication type needed to send mail, depends on mail_smtpmode if this is - * used Can be LOGIN (default), PLAIN or NTLM + * This depends on ``mail_smtpmode``. If SMTP authentication is required, choose + * the authentication type as ``LOGIN`` (default) or ``PLAIN``. */ 'mail_smtpauthtype' => 'LOGIN', /** - * Username to use for sendmail mail, depends on mail_smtpauth if this is used + * This depends on ``mail_smtpauth``. Specify the username for authenticating to + * the SMTP server. */ 'mail_smtpname' => '', /** - * Password to use for sendmail mail, depends on mail_smtpauth if this is used + * This depends on ``mail_smtpauth``. Specify the password for authenticating to + * the SMTP server. */ 'mail_smtppassword' => '', @@ -254,40 +297,48 @@ $CONFIG = array( /** * The automatic hostname detection of ownCloud can fail in certain reverse - * proxy and CLI/cron situations. This option allows to manually override the - * automatic detection. You can also add a port. For example - * 'www.example.com:88' + * proxy and CLI/cron situations. This option allows you to manually override + * the automatic detection; for example ``www.example.com``, or specify the port + * ``www.example.com:8080``. */ 'overwritehost' => '', /** - * The automatic protocol detection of ownCloud can fail in certain reverse - * proxy and CLI/cron situations. This option allows to manually override the - * protocol detection. For example 'https' + * When generating URLs, ownCloud attempts to detect whether the server is + * accessed via ``https`` or ``http``. However, if ownCloud is behind a proxy + * and the proxy handles the ``https`` calls, ownCloud would not know that + * ``ssl`` is in use, which would result in incorrect URLs being generated. + * Valid values are ``http`` and ``https``. */ 'overwriteprotocol' => '', /** - * The automatic webroot detection of ownCloud can fail in certain reverse proxy - * and CLI/cron situations. This option allows to manually override the - * automatic detection. For example '/domain.tld/ownCloud'. The value '/' can be - * used to remove the root. + * ownCloud attempts to detect the webroot for generating URLs automatically. + * For example, if ``www.example.com/owncloud`` is the URL pointing to the + * ownCloud instance, the webroot is ``/owncloud``. When proxies are in use, it + * may be difficult for ownCloud to detect this parameter, resulting in invalid + * URLs. */ 'overwritewebroot' => '', /** - * The automatic detection of ownCloud can fail in certain reverse proxy and - * CLI/cron situations. This option allows to define a manually override - * condition as regular expression for the remote ip address. For example - * '^10\.0\.0\.[1-3]$' + * This option allows you to define a manual override condition as a regular + * expression for the remote IP address. For example, defining a range of IP + * addresses starting with ``10.`` and ending with 1 to 3: ``^10\.0\.0\.[1-3]$`` */ 'overwritecondaddr' => '', /** - * A proxy to use to connect to the internet. For example 'myproxy.org:88' + * The URL of your proxy server, for example ``proxy.example.com:8081``. */ 'proxy' => '', +/** + * The optional authentication for the proxy to use to connect to the internet. + * The format is: ``username:password``. + */ +'proxyuserpwd' => '', + /** * Deleted Items @@ -296,14 +347,14 @@ $CONFIG = array( */ /** - * How long should ownCloud keep deleted files in the trash bin, default value: - * 30 days + * When the delete app is enabled (default), this is the number of days a file + * will be kept in the trash bin. Default is 30 days. */ 'trashbin_retention_obligation' => 30, /** - * Disable/Enable auto expire for the trash bin, by default auto expire is - * enabled + * Disable or enable auto-expiration for the trash bin. By default + * auto-expiration is enabled. */ 'trashbin_auto_expire' => true, @@ -311,35 +362,37 @@ $CONFIG = array( /** * ownCloud Verifications * - * ownCloud performs several verification checks. There are two options, 'true' - * and 'false'. + * ownCloud performs several verification checks. There are two options, + * ``true`` and ``false``. */ /** - * Ensure that 3rdparty applications follows coding guidelines + * Check 3rd party apps to make sure they are using the private API and not the + * public API. If the app uses the public API it cannot be installed. */ 'appcodechecker' => true, /** - * Check if ownCloud is up to date and shows a notification if a new version is - * available + * Check if ownCloud is up-to-date. */ 'updatechecker' => true, /** - * Are we connected to the internet or are we running in a closed network? + * Is ownCloud connected to the Internet or running in a closed network? */ 'has_internet_connection' => true, /** - * Check if the ownCloud WebDAV server is working correctly. Can be disabled if - * not needed in special situations + * Allows ownCloud to verify a working WebDAV connection. This is done by + * attempting to make a WebDAV request from PHP. */ 'check_for_working_webdav' => true, /** - * Check if .htaccess protection of data is working correctly. Can be disabled - * if not needed in special situations + * Verifies whether the ``.htaccess`` file may be modified by ownCloud. If set + * to ``false``, this check will not be performed. If the file cannot be + * modified, items such as large file uploads cannot be performed. This check + * only affects Apache servers. */ 'check_for_working_htaccess' => true, @@ -349,54 +402,51 @@ $CONFIG = array( */ /** - * Place to log to, can be 'owncloud' and 'syslog' (owncloud is log menu item in - * admin menu) + * By default the ownCloud logs are sent to the ``owncloud.log`` file in the + * default ownCloud data directory. If syslogging is desired, set this parameter + * to ``syslog``. */ 'log_type' => 'owncloud', /** - * File for the ownCloud logger to log to, (default is owncloud.log in the data - * dir) + * Change the ownCloud logfile name from ``owncloud.log`` to something else. */ 'logfile' => 'owncloud.log', /** - * Loglevel to start logging at. 0 = DEBUG, 1 = INFO, 2 = WARN, 3 = ERROR - * (default is WARN) + * Valid values are: 0 = Debug, 1 = Info, 2 = Warning, 3 = Error. The default + * value is Warning. */ 'loglevel' => 2, /** - * date format to be used while writing to the ownCloud logfile + * This uses PHP.date formatting; see http://php.net/manual/en/function.date.php */ 'logdateformat' => 'F d, Y H:i:s', /** - * timezone used while writing to the ownCloud logfile (default: UTC) + * The default timezone for logfiles is UTC. You may change this; see + * http://php.net/manual/en/timezones.php */ 'logtimezone' => 'Europe/Berlin', /** - * Append all database queries and parameters to the log file. (watch out, this - * option can increase the size of your log file) + * Append all database queries and parameters to the log file. Use this only for + * debugging, as your logfile will become huge. */ 'log_query' => false, /** - * Whether ownCloud should log the last successfull cron exec + * Log successful cron runs. */ 'cron_log' => true, /** - * Configure the size in bytes log rotation should happen, 0 or false disables - * the rotation. This rotates the current ownCloud logfile to a new name, this - * way the total log usage will stay limited and older entries are available for - * a while longer. The total disk usage is twice the configured size. - * - * WARNING: When you use this, the log entries will eventually be lost. - * - * Example: To set this to 100 MiB, use the value: 104857600 (1024*1024*100 - * bytes). + * Enables log rotation and limits the total size of logfiles. The default is 0, + * or no rotation. Specify a size in bytes, for example 50000000 (50 megabytes). + * A new logfile is created with a new name when the old logfile reaches your + * limit. The total size of all logfiles is double the + * ``log_rotate_sizerotation`` value. */ 'log_rotate_size' => false, @@ -408,17 +458,21 @@ $CONFIG = array( */ /** - * Path to the parent directory of the 3rdparty directory + * ownCloud uses some 3rd party PHP components to provide certain functionality. + * These components are shipped as part of the software package and reside in + * ``owncloud/3rdparty``. Use this option to configure a different location. */ '3rdpartyroot' => '', /** - * URL to the parent directory of the 3rdparty directory, as seen by the browser + * If you have an alternate ``3rdpartyroot``, you must also configure the URL as + * seen by a Web browser. */ '3rdpartyurl' => '', /** - * links to custom clients + * This section is for configuring the download links for ownCloud clients, as + * seen in the first-run wizard and on Personal pages. */ 'customclient_desktop' => 'http://owncloud.org/sync-clients/', @@ -434,25 +488,24 @@ $CONFIG = array( */ /** - * Enable installing apps from the appstore + * When enabled, admins may install apps from the ownCloud app store. */ 'appstoreenabled' => true, /** - * URL of the appstore to use, server should understand OCS + * The URL of the appstore to use. */ 'appstoreurl' => 'https://api.owncloud.com/v1', /** - * Set an array of path for your apps directories - * - * key 'path' is for the fs path and the key 'url' is for the http path to your - * applications paths. 'writable' indicates whether the user can install apps in - * this folder. You must have at least 1 app folder writable or you must set the - * parameter 'appstoreenabled' to false + * Use the ``apps_paths`` parameter to set the location of the Apps directory, + * which should be scanned for available apps, and where user-specific apps + * should be installed from the Apps store. The ``path`` defines the absolute + * file system path to the app folder. The key ``url`` defines the HTTP web path + * to that folder, starting from the ownCloud web root. The key ``writable`` + * indicates if a user can install apps in that folder. */ 'apps_paths' => array( - array( 'path'=> '/var/www/owncloud/apps', 'url' => '/apps', @@ -478,15 +531,20 @@ $CONFIG = array( */ 'enable_previews' => true, /** - * the max width of a generated preview, if value is null, there is no limit + * The maximum width, in pixels, of a preview. A value of ``null`` means there + * is no limit. */ 'preview_max_x' => null, /** - * the max height of a generated preview, if value is null, there is no limit + * The maximum height, in pixels, of a preview. A value of ``null`` means there + * is no limit. */ 'preview_max_y' => null, /** - * the max factor to scale a preview, default is set to 10 + * If a lot of small pictures are stored on the ownCloud instance and the + * preview system generates blurry previews, you might want to consider setting + * a maximum scale factor. By default, pictures are upscaled to 10 times the + * original size. A value of ``1`` or ``null`` disables scaling. */ 'preview_max_scale_factor' => 10, /** @@ -494,7 +552,7 @@ $CONFIG = array( */ 'preview_libreoffice_path' => '/usr/bin/libreoffice', /** - * cl parameters for libreoffice / openoffice + * Use this if LibreOffice requires additional arguments. */ 'preview_office_cl_parameters' => ' --headless --nologo --nofirststartwizard --invisible --norestore '. @@ -548,7 +606,8 @@ $CONFIG = array( 'maintenance' => false, /** - * whether usage of the instance should be restricted to admin users only + * When set to ``true``, the ownCloud instance will be unavailable for all users + * who are not in the ``admin`` group. */ 'singleuser' => false, @@ -558,12 +617,13 @@ $CONFIG = array( */ /** - * Force use of HTTPS connection (true = use HTTPS) + * Change this to ``true`` to require HTTPS for all connections, and to reject + * HTTP requests. */ 'forcessl' => false, /** - * Extra SSL options to be used for configuration + * Extra SSL options to be used for configuration. */ 'openssl' => array( 'config' => '/absolute/location/of/openssl.cnf', @@ -581,30 +641,33 @@ $CONFIG = array( 'blacklisted_files' => array('.htaccess'), /** - * define default folder for shared files and folders + * Define a default folder for shared files and folders other than root. */ 'share_folder' => '/', /** - * Theme to use for ownCloud + * If you are applying a theme to ownCloud, enter the name of the theme here. + * The default location for themes is ``owncloud/themes/``. */ 'theme' => '', /** - * Enable/disable X-Frame-Restriction - * - * HIGH SECURITY RISK IF DISABLED + * X-Frame-Restriction is a header which prevents browsers from showing the site + * inside an iframe. This may be used to prevent clickjacking. It is risky to + * disable this, so leave it set at ``true``. */ 'xframe_restriction' => true, /** - * default cipher used for file encryption, currently we support AES-128-CFB and - * AES-256-CFB + * The default cipher for encrypting files. Currently AES-128-CFB and + * AES-256-CFB are supported. */ 'cipher' => 'AES-256-CFB', /** - * memcached servers (Only used when xCache, APC and APCu are absent.) + * Server details for one or more memcached servers to use for memory caching. + * Memcache is only used if other memory cache options (xcache, apc, apcu) are + * not available. */ 'memcached_servers' => array( // hostname, port and optional weight. Also see: @@ -615,50 +678,55 @@ $CONFIG = array( ), /** - * Location of the cache folder, defaults to 'data/$user/cache' where '$user' is - * the current user. - * - * When specified, the format will change to '$cache_path/$user' where - * '$cache_path' is the configured cache directory and '$user' is the user. + * Location of the cache folder, defaults to ``data/$user/cache`` where + * ``$user`` is the current user. When specified, the format will change to + * ``$cache_path/$user`` where ``$cache_path`` is the configured cache directory + * and ``$user`` is the user. */ 'cache_path' => '', /** * EXPERIMENTAL: option whether to include external storage in quota - * calculation, defaults to false + * calculation, defaults to false. */ 'quota_include_external_storage' => false, /** - * specifies how often the filesystem is checked for changes made outside - * ownCloud + * Specifies how often the filesystem is checked for changes made outside + * ownCloud. * - * 0 -> never check the filesystem for outside changes, provides a performance + * 0 -> Never check the filesystem for outside changes, provides a performance * increase when it's certain that no changes are made directly to the * filesystem * - * 1 -> check each file or folder at most once per request, recommended for - * general use if outside changes might happen + * 1 -> Check each file or folder at most once per request, reccomended for + * general use if outside changes might happen. * - * 2 -> check every time the filesystem is used, causes a performance hit when - * using external storages, not recommended for regular use + * 2 -> Check every time the filesystem is used, causes a performance hit when + * using external storages, not recomended for regular use. */ 'filesystem_check_changes' => 1, /** - * where mount.json file should be stored + * All css and js files will be served by the web server statically in one js + * file and one css file. + */ +'asset-pipeline.enabled' => false, + +/** + * Where ``mount.json`` file should be stored, defaults to ``data/mount.json`` */ 'mount_file' => 'data/mount.json', /** - * If true, prevent ownCloud from changing the cache due to changes in the - * filesystem for all storage + * When ``true``, prevent ownCloud from changing the cache due to changes in the + * filesystem for all storage. */ 'filesystem_cache_readonly' => false, /** * The example below shows how to configure ownCloud to store all files in a - * swift object storage + * swift object storage. * * It is important to note that ownCloud in object store mode will expect * exclusive access to the object store container because it only stores the @@ -705,21 +773,4 @@ $CONFIG = array( "style-src 'self' 'unsafe-inline'; frame-src *; img-src *; ". "font-src 'self' data:; media-src *", - -/** - * Forgotten ones - */ - -/** - * The optional authentication for the proxy to use to connect to the internet. - * The format is: [username]:[password] - */ -'proxyuserpwd' => '', - -/** - * all css and js files will be served by the web server statically in one js - * file and ons css file - */ -'asset-pipeline.enabled' => false, - ); -- 2.39.5