Merge pull request #576 from sbesson/11787_server_upgrade

Review server upgrade and password provider pages

omero/developers/Server/PasswordProvider.txt

@@ -8,7 +8,7 @@ Several implementations exist currently:
 
 -  :source:`ome.security.auth.JdbcPasswordProvider <components/server/src/ome/security/auth/JdbcPasswordProvider.java>`
    is the most common provider, and uses the "password" table for
-   storing MD5 encrypted passwords per user.
+   storing passwords hashed using MD5 and salt per user.
 -  :source:`ome.security.auth.FilePasswordProvider <components/server/src/ome/security/auth/FilePasswordProvider.java>`
    is rarely used, but in some scenarios may be useful since it permits
    setting usernames and passwords in a plain text file.
@@ -38,10 +38,10 @@ Things to keep in mind
    :source:`LoginAttemptMessage <components/server/src/ome/services/messages/LoginAttemptMessage.java>`
    so that any :doc:`/developers/Server/LoginAttemptListener`
    implementation can properly react to failed logins. Your
-   implementation should probably do the same
+   implementation should probably do the same.
 
 -  When dealing with chains of password providers, an implementation can
    safely return null from ``checkPassword`` to say "I don't know
    anything about this". This is only important if you configure your
    own chained password provider with your new implementation as one of
-   the elements..
+   the elements.

omero/sysadmins/index.txt

@@ -79,7 +79,6 @@ Server Maintenance
     server-backup-and-restore
     server-upgrade
     UpgradeCheck
-    server-migration-fs
     command-line-interface
 
 
@@ -92,8 +91,5 @@ Advanced topics
     :titlesonly:
 
     server-permissions
-    server-advanced-configuration
     dropbox
-    fs-upload-configuration
-    server-ldap
     grid

omero/sysadmins/server-ldap.txt

@@ -270,6 +270,15 @@ command:
 When the LDAP password provider implementation changes, previous versions can
 be configured as necessary.
 
+chainedPasswordProviderNoSalt
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``chainedPasswordProviderNoSalt`` uses the version of the JDBC password
+provider without password salting support as available in the OMERO 4.4.x
+series. To enable it, use::
+
+    bin/omero config set omero.security.password_provider chainedPasswordProviderNoSalt
+
 chainedPasswordProvider431
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 

omero/sysadmins/server-upgrade.txt

@@ -19,9 +19,6 @@ to disable this functionality you should do so now as outlined on the
     suitable version of PostgreSQL to enable successful upgrading of
     the database.
 
-    **Also be aware that at present there is no way of directly upgrading
-    OMERO.server from the 4.x line to the OMERO.fs (5.x) version.**
-
 If you encounter errors during a OMERO upgrade, database upgrade, etc.
 you should retain as much log information as possible and notify the
 OMERO.server team via the mailing lists available on the
@@ -37,6 +34,16 @@ below. Please refer to each section for additional details.
     :local:
     :depth: 1
 
+.. warning::
+	With 5.0.0-beta2, the default JDBC password provider has been modified to
+	add password salting support. This implies that once a server has been
+	upgraded and deployed, if passwords are modified, you will not be able
+	to easily revert to a configuration without salting. To keep using the
+	legacy password provider without salting support, you will need to
+	configure ``omero.security.password_provider`` to use the legacy
+	``chainedPasswordProviderNoSalt`` as described in the
+	:ref:`legacy_password_providers` section.
+
 .. warning:: The passwords and logins used here are examples. Please consult
     the :ref:`troubleshooting-password` section for explanation.  In particular,
     make sure to replace the values of **db_user** and **omero_database**
@@ -62,10 +69,10 @@ Before copying the new binaries, stop the existing server::
     $ bin/omero web stop
     $ bin/omero admin stop
 
-Your OMERO configuration is stored using ``config.xml`` in the``etc/grid`` 
-directory under your OMERO.server directory. Assuming you have not made any 
-file changes within your OMERO.server distribution directory, you are safe to 
-follow the following upgrade procedure:
+Your OMERO configuration is stored using :file:`config.xml` in the
+:file:`etc/grid` directory under your OMERO.server directory. Assuming you
+have not made any file changes within your OMERO.server distribution
+directory, you are safe to follow the following upgrade procedure:
 
 .. parsed-literal::
 
@@ -92,16 +99,41 @@ Run the upgrade script
 ^^^^^^^^^^^^^^^^^^^^^^	
 
 You **must** use the same username and password you have defined during
-:doc:`unix/server-installation`. The |version| upgrade script should execute in a short time.
+:doc:`unix/server-installation`. The |version| upgrade script should execute
+in a short time.
+
+From a |previousversion|.x server
+"""""""""""""""""""""""""""""""""
 
 .. parsed-literal::
 
     $ cd |OMEROserverzip|
-    $ psql -h localhost -U **db_user** **omero_database** < sql/psql/OMERO\ |version|\_\_0/OMERO |previousversion|\_\_0.sql
+    $ psql -h localhost -U **db_user** **omero_database** < sql/psql/OMERO\ |version|\_\_0/OMERO\ |previousversion|\_\_0.sql
     Password for user **db_user**:
     ...
     ...
-                               status                                
+                               status
+    ---------------------------------------------------------------------
+                                                                        +
+                                                                        +
+                                                                        +
+    YOU HAVE SUCCESSFULLY UPGRADED YOUR DATABASE TO VERSION OMERO |version|\_\_0+
+                                                                        +
+                                                                        +
+
+    (1 row)
+
+From a 5.0.0-beta1 server
+"""""""""""""""""""""""""
+
+.. parsed-literal::
+
+    $ cd |OMEROserverzip|
+    $ psql -h localhost -U **db_user** **omero_database** < sql/psql/OMERO\ |version|\_\_0/OMERO\ |version|\DEV\_\_6.sql
+    Password for user **db_user**:
+    ...
+    ...
+                               status
     ---------------------------------------------------------------------
                                                                         +
                                                                         +
@@ -120,8 +152,8 @@ database which can both save disk space and speed up access times.
 
 .. parsed-literal::
 
-    $ psql -h localhost -U **db_user** **omero_database** -c "REINDEX DATABASE **omero_database** FORCE;"
-    $ psql -h localhost -U **db_user** **omero_database** -c "VACUUM FULL VERBOSE ANALYZE;"
+    $ psql -h localhost -U **db_user** **omero_database** -c 'REINDEX DATABASE "**omero_database**" FORCE;'
+    $ psql -h localhost -U **db_user** **omero_database** -c 'VACUUM FULL VERBOSE ANALYZE;'
 
 .. _upgrademergescript:
 
@@ -140,8 +172,8 @@ For further information on managing your scripts, refer to
 :doc:`installing-scripts`. If you require help, please contact the OME 
 developers.
 
-Update your environment variables
----------------------------------
+Update your configuration
+-------------------------
 
 Environment variables
 ^^^^^^^^^^^^^^^^^^^^^
@@ -151,6 +183,15 @@ make sure to update any system environment variables. Before restarting
 the server, make sure your PATH and PYTHONPATH system environment
 variables are pointing to the new locations.
 
+JVM memory settings
+^^^^^^^^^^^^^^^^^^^
+
+If you modified your memory settings, these changes will be lost and you will
+need to update the memory settings for the new server. Refer to the
+`JVM memory settings` sub-section of the OMERO.server installation section
+(:doc:`Unix <unix/server-installation>` or
+:doc:`Windows <windows/server-installation>`) for more information.
+
 Changes to OMERO.web URLs
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 

omero/sysadmins/whatsnew.txt

@@ -1,8 +1,9 @@
 What's new for OMERO 5
 ======================
 
-- :doc:`server-migration-fs` has been added and :doc:`server-upgrade` updated 
-  to clarify the position on upgrading from 4.4 to OMERO 5.
+- :doc:`server-upgrade` has been updated to explain the server upgrade
+  process from 4.4 to OMERO 5 and describe the introduction of password
+  salting support.
 
 - :doc:`fs-upload-configuration` has been added to explain the server-side FS 
   workflow for importing files.