Merge branch 'release/9.5.0'

.tx/config

@@ -31,3 +31,8 @@ source_lang = en
 file_filter = source/locale/<lang>/LC_MESSAGES/install/wizard.po
 source_file = build/locale/install/wizard.pot
 source_lang = en
+
+[glpi-install.install--advanced-configuration]
+file_filter = source/locale/<lang>/LC_MESSAGES/install/advanced-configuration.po
+source_file = build/locale/install/advanced-configuration.pot
+source_lang = en

source/command-line.rst

@@ -10,6 +10,10 @@ Calling ``php bin/console`` from GLPI directory displays the list of available c
 
    If APCu is installed on your system, it may fail from command line since default configuration disables it from command-line. To change that, set ``apc.enable_cli`` to ``on`` in your APCu configuration file.
 
+.. warning::
+
+   When using cli tools, please check the system user you are currently logged in with, and permissions on files and directories. With a wrong user, logs, cache and other files may be created with rights that would not allow your webserver to read or write on thos files!
+
 .. _cdline_options:
 
 Console options
@@ -27,20 +31,58 @@ For every console command, following options are available:
 
 .. _cdline_install:
 
+Additional install and update tools
+-----------------------------------
+
+Check requirements
+^^^^^^^^^^^^^^^^^^
+
+Before installing or upgrading, requirements are automatically checked; but you can run them separately and see state for all of them using the ``glpi:system:check_requirements`` command.
+
+Enable/Disable maintenance
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+GLPI provides a maintenance mode that can be activated prior to an update, and deactivated after all has been checked.
+
+Just use the ``glpi:maintenance:enable`` and ``glpi:maintenance:disable`` commands.
+
 Install
 -------
 
 The ``php bin/console db:install`` has been made to install GLPI database in CLI mode.
 
 Possible options for this command are:
 
- * ``-H``, ``--db-host`` host name (`localhost` per default)
- * ``-P``, ``--db-port`` database port (default MySQL port if option is not defined)
- * ``-d``, ``--db-name`` database name
- * ``-u``, ``--db-user`` database user name
- * ``-p``, ``--db-password`` database user's pasword
- * ``-L``, ``--default-language`` default language of GLPI (`en_GB` per default)
- * ``-f``, ``--force`` do not check if GLPI is already installed and drop what would exists
+ * ``-r``, ``--reconfigure`` to enable overriding of any existing DB configuration file
+ * ``-f``, ``--force`` to force execution of installation even if database is not empty
+ * ``-L``, ``--default-language=DEFAULT_LANGUAGE`` default language of GLPI (`en_GB` per default)
+ * ``-H``, ``--db-host=DB_HOST`` host name (`localhost` per default)
+ * ``-P``, ``--db-port=DB_PORT`` database port (default MySQL port if option is not defined)
+ * ``-d``, ``--db-name=DB_NAME`` database name
+ * ``-u``, ``--db-user=DB_USER`` database user name
+ * ``-p``, ``--db-password=DB_PASSWORD`` database user's pasword (use it without value to be prompted for password)
+
+If mandatory options are not specified in the command call, the console will ask for them.
+
+Database connection parameters may be ommited if a configuration file already exists.
+
+See also :ref:`console options <cdline_options>`.
+
+Database connection configuration
+---------------------------------
+
+   .. versionadded:: 9.5.0
+
+The ``php bin/console db:configure`` has been made to define database connection parameters in CLI mode.
+
+Possible options for this command are:
+
+ * ``-r``, ``--reconfigure`` to enable overriding of any existing DB configuration file
+ * ``-H``, ``--db-host=DB_HOST`` host name (`localhost` per default)
+ * ``-P``, ``--db-port=DB_PORT`` database port (default MySQL port if option is not defined)
+ * ``-d``, ``--db-name=DB_NAME`` database name
+ * ``-u``, ``--db-user=DB_USER`` database user name
+ * ``-p``, ``--db-password=DB_PASSWORD`` database user's pasword (use it without value to be prompted for password)
 
 If mandatory options are not specified in the command call, the console will ask for them.
 
@@ -66,7 +108,25 @@ Possible options for this command are:
 
 See also :ref:`console options <cdline_options>`.
 
-Database tools
+Security key
+------------
+
+.. versionadded:: 9.4.6
+
+.. note:: GLPI key file is available for GLPI >= 9.4.6 but is not mandatory. As of GLPI 9.5, using the key file will be mandatory.
+
+In order to store some sensitive data, GLPI relies on a homemade encryption/decryption tool, which uses a key to:
+
+* encrypt data before storing them in the database,
+* decrypt data that has been retrieved from the database.
+
+The ``php bin/console glpi:security:change_key`` command allows to change the key, if it has been compromised for example. By default, command will:
+
+* generate a new key and and store it in the key file,
+* update all configured fields (for core and compatible plugins) to use the new key,
+* update all configuration entries listed (for core and compatible plugins) to use the new key.
+
+Various tools
 --------------
 
 Database schema check
@@ -91,8 +151,30 @@ If you have any diff, output will looks like :
     +  `pattern` text
        primary key (`id`)
 
-Tasks tools
------------
+LDAP synchonization
+^^^^^^^^^^^^^^^^^^^
+
+The ``bin/console glpi:ldap:synchronize_users`` command can be used to synchronize users against LDAP server informations.
+
+Possible options for this command are:
+
+ * ``-c``, ``--only-create-new`` only create new users
+ * ``-u``, ``--only-update-existing`` only update existing users
+ * ``-s``, ``--ldap-server-id[=LDAP-SERVER-ID]`` synchronize only users attached to this LDAP server (multiple values allowed)
+ * ``-f``, ``--ldap-filter[=LDAP-FILTER]`` filter to apply on LDAP search
+ * ``--begin-date[=BEGIN-DATE]`` begin date to apply in "modifyTimestamp" filter
+ * ``--end-date[=END-DATE]`` end date to apply in "modifyTimestamp" filter
+ * ``-d``, ``--deleted-user-strategy[=DELETED-USER-STRATEGY]`` force strategy used for deleted users:
+
+    * 0: Preserve
+    * 1: Put in trashbin
+    * 2: Withdraw dynamic authorizations and groups
+    * 3: Disable
+    * 4: Disable + Withdraw dynamic authorizations and groups
+
+See http://php.net/manual/en/datetime.formats.php for supported date formats in ``--begin-date`` and ``--end-date`` options.
+
+See also :ref:`console options <cdline_options>`.
 
 Task unlock
 ^^^^^^^^^^^
@@ -112,6 +194,26 @@ Possible options for this command are:
 
 See also :ref:`console options <cdline_options>`.
 
+Plugins tools
+-------------
+
+    .. versionadded:: 9.5
+
+Some command line tolls are also available to manage plugins from command line:
+
+ * ``glpi:plugin:install``
+ * ``glpi:plugin:activate``
+ * ``glpi:plugin:deactivate``
+
+In order to install ``MyGreatPlugin``; you should end with something like:
+
+::
+
+   $ ./bin/console glpi:plugin:install MyGreatPlugin
+   $ ./bin/console glpi:plugin:activate MyGreatPlugin
+
+Each of those plugin commands can take a plugin name as argument, or the ``--all`` flag to be ran on all plugins.
+
 Migration tools
 ---------------
 
@@ -132,3 +234,37 @@ Missing timestamps builder
 Prior to GLPI 9.1.0, fields corresponding to creation and modification dates were not existing.
 
 The ``php bin/console glpi:migration:build_missing_timestamps`` command can be used to rebuild missing values using available logs.
+
+Use timestamp data type
+^^^^^^^^^^^^^^^^^^^^^^^
+
+   .. versionadded:: 9.5.0
+
+Many date fields were using the ``DATETIME`` type, but this does not allow to rely on timezones. Timezone support requires all fields to use ``TIMESTAMP`` data type, but this query can be very long and therefore is not included in the standard update process.
+
+Using the ``glpi:migration:timestamps`` command will change those fields to the correct data type, but read :doc:`documentation on timezones <timezones>` before.
+
+.. warning::
+
+   Ensure to backup your database before!
+
+Migrate Domains plugin
+^^^^^^^^^^^^^^^^^^^^^^
+
+   .. versionadded:: 9.5.0
+
+Domains in GLPI have evolved from a simple dropdown to a more complex object, including records management among others. Therefore, the Domains plugins feature are now included in core.
+
+To migrate your plugin data; use the ``glpi:migration:domains_plugin_to_core`` command. Presence of the plugin is mandatory so checks can be run, you can use the ``--without-plugin`` switch but this is not recommended. If you were using an older version of the plugin than the one required, you can use the ``--update-plugin`` flag.
+
+At the end, all domains types, domains and item relations will be migrated in core tables.
+
+Migrate Racks plugin
+^^^^^^^^^^^^^^^^^^^^^^
+
+   .. versionadded:: 9.5.0
+
+Since GLPI 9.3.0, data center infrastructure management is available as a core feature. A migration script from Racks plugin was provided inside the ``scripts`` directory.
+Since GLPI 9.5.0, this migration script has been refactored and moved inside the CLI console.
+
+To migrate your plugin data; use the ``glpi:migration:racks_plugin_to_core`` command. Presence of the plugin is mandatory so checks can be run, you can use the ``--without-plugin`` switch but this is not recommended. If you were using an older version of the plugin than the one required, you can use the ``--update-plugin`` flag.

source/conf.py

@@ -79,9 +79,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'9.4'
+version = u'9.5'
 # The full version, including alpha/beta/rc tags.
-release = u'9.4'
+release = u'9.5'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

source/index.rst

@@ -16,5 +16,7 @@ This documentation presents `GLPI <http://glpi-project.org>`_ installation instr
    prerequisites
    install/index
    install/wizard
+   timezones
    update
    command-line
+   install/advanced-configuration.rst

source/install/advanced-configuration.rst

@@ -0,0 +1,22 @@
+Advanced configuration
+======================
+
+SSL connection to database
+--------------------------
+
+   .. versionadded:: 9.5.0
+
+Once installation is done, you can update the ``config/config_db.php`` to define SSL connection parameters.
+Available parameters corresponds to parameters used by `mysqli::ssl_set() <https://www.php.net/manual/en/mysqli.ssl-set.php>`_:
+
+* ``$dbssl`` defines if connection should use SSL (`false` per default)
+* ``$dbsslkey`` path name to the key file (`null` per default)
+* ``$dbsslcert`` path name to the certificate file (`null` per default)
+* ``$dbsslca`` path name to the certificate authority file (`null` per default)
+* ``$dbsslcapath`` pathname to a directory that contains trusted SSL CA certificates in PEM format (`null` per default)
+* ``$dbsslcacipher`` list of allowable ciphers to use for SSL encryption (`null` per default)
+
+.. warning::
+
+   For now it is not possible to define SSL connection parameters prior or during the installation process.
+   It has to be done once installation has been done.

source/install/index.rst

@@ -44,6 +44,8 @@ GLPI installation itself is composed of three steps:
 
 Once these three steps have been completed the application is ready to be used.
 
+If you need to set advanced configuration, like SSL connection parameters, please refer to :doc:`advanced configuration <advanced-configuration>`.
+
 Files and directories locations
 -------------------------------
 
@@ -69,9 +71,9 @@ Directories choice is entirely up to you; the following example will follow the
 
 Our GLPI instance will be installed in ``/var/www/glpi``, a specific virtual host in the web server configuration will reflect this path.
 
-GLPI configuration will be stored in ``/etc/glpi``, just copy the ``config`` directory to this place. GLPI requires read rights on this directory to work; and write rights during the installation process.
+GLPI configuration will be stored in ``/etc/glpi``, just copy the contents of the ``config`` directory to this place. GLPI requires read rights on this directory to work; and write rights during the installation process.
 
-GLPI data will be stored in ``/var/lib/glpi``, just copy the ``files`` directory to this place. GLPI requires read and write rights on this directory.
+GLPI data will be stored in ``/var/lib/glpi``, just copy the contents of the ``files`` directory to this place. GLPI requires read and write rights on this directory.
 
 GLPI logs files will be stored in ``/var/log/glpi``, there is nothing to copy here, just create the directory. GLPI requires read and write access on this directory.
 

source/install/wizard.rst

@@ -43,14 +43,14 @@ Click on install.
 Environment checks
 ^^^^^^^^^^^^^^^^^^
 
-This step will check if prerequisites are met. If thery're not, it is not possible to continue and an explicit error message will tell you about what is wrong and what to do before trying again.
+This step will check if prerequisites are met. If they're not, it is not possible to continue and an explicit error message will tell you about what is wrong and what to do before trying again.
 
 .. image:: images/setup.png
    :alt: Check prerequisites
    :align: center
    :scale: 50%
 
-Some prerequisites are optionals, it will be possible to continue installation event if thery're not met.
+Some prerequisites are optionals, it will be possible to continue installation event if they're not met.
 
 Database connection
 ^^^^^^^^^^^^^^^^^^^