Merge pull request #645 from emuus/3.8.fp1-migrate38

add section for migrating 3.7 to 3.8 (in 3.8fp1)

admin/en/source/pages/upgrade/migrating-to38.rst

@@ -0,0 +1,131 @@
+.. Copyright 2017 FUJITSU LIMITED
+
+
+.. _migrate-to38:
+
+Migrating UForge from 3.7 to 3.8
+--------------------------------
+
+Before you start upgrading from UForge AppCenter version 3.7 to version 3.8, please note that the UForge root user password is now subject to restrictions. The UForge root user password must be 8 characters or more, contain at least 1 upper case letter, 1 lower case letter and 1 number. Characters - and _ are also allowed.
+
+If your current UForge root user password matches those requirements, you do not need to make any changes. If your current UForge root user password does not match these requirements, you will have to change it in your UForge 3.7 AppCenter before starting migration.
+
+A separate set of scripts and associated README.txt file is available on the `UShareSoft repository <http://https://repository.usharesoft.com/downloads/changePasswordScripts.tar.gz>`_.
+
+	#. Deploy UForge 3.8 with the same topology as the original UForge 3.7 one to migrate, using the CentOS 7 UForge in a box ISO
+
+		* Deploy without any OS and format
+		* Use the same organisation name (UFORGE_DEFAULT_ORG_NAME info) as the one defined in ``/etc/UShareSoft/auth.conf on the <source_db>``
+		* Use the same admin password (UFORGE_DB_ADMIN_PASSWORD info) as the one defined in ``/etc/UShareSoft/auth.conf on the <source_db>``
+
+	#. Upgrade your UForge to the latest 3.8 patch, for each node of the platform (if multi-node the following order should be respected: compute notes, db nodes, web service and UI nodes).
+
+ 	.. code-block:: shell
+ 
+ 		# yum update -y uforge-common
+ 		# yum update -y uforge-gen uforge uforge-cli uforge-client
+
+ 	#. To upgrade from UForge 3.8 to a 3.8.fpx, you have to do the following on each node composing the topology. The following order should be respected: compute notes, db nodes, web service and UI nodes:
+
+ 		a) Edit ``/etc/yum.repos.d/uforge-ee-centos.repo`` and update ``baseurl`` info replacing ``stable/3.8/official/centos/releases/$releasever/$basearch/`` by ``stable/latest/official/centos/releases/$releasever/$basearch/``.
+		b) Run the following command on each node:
+
+		.. code-block:: shell
+ 
+	 		# yum update -y uforge-common
+	 		# yum update -y uforge-gen uforge uforge-cli uforge-client
+
+	#. The source UForge DB server has to be upgraded to the last 3.7 version. On the <source_db> run the following commands:
+
+	.. code-block:: shell
+
+		# yum update -y uforge-common
+		# yum update -y uforge-gen uforge uforge-cli uforge-client
+
+	#. The source UForge Web Service server has to be upgraded to the last 3.7 version. On the <source_ws> run the following commands:
+
+	.. code-block:: shell 
+
+		# yum update -y uforge-common
+		# yum update -y uforge-gen uforge uforge-cli uforge-client
+		# service tomcat stop
+
+	#. Once both platforms are ready, on <source_db> run the following commands:
+
+	.. code-block:: shell
+
+		# service oar-server stop
+		# service OpenDJ  stop
+		# cd /tmp/USER_DATA
+		# source /etc/UShareSoft/auth.conf
+		# mysqldump -u${UFORGE_DB_ADMIN_LOGIN} -p${UFORGE_DB_ADMIN_PASSWORD} --routines --triggers --databases oar syncope uauthdb usharedb > db_backup_3.7.sql
+		# /opt/OpenDJ/bin/export-ldif -l uforge-export.ldif -n userRoot
+		# rsync  -avl -H -F --progress /tmp/USER_DATA/ root@<target_db>:/tmp/USER_DATA/
+
+	#. Once the previous rsync command has finished oar-server and opendj services have to be stopped. On <target_db > run the following commands:
+
+	.. code-block:: shell
+
+		# systemctl stop oar-server
+		# service opendj stop
+
+	#. Once oar-server and opendj are stoppen you need to stop Tomcat. On <target_ws> run the following command:
+
+	.. code-block:: shell
+
+		# service tomcat stop
+
+	#. The DB on <target_db> server has to be reset. Tun the following commands:
+
+	.. code-block:: shell
+
+		# source /etc/UShareSoft/auth.conf
+		# echo "DROP DATABASE usharedb;" | mysql -u${UFORGE_DB_ADMIN_LOGIN} -p${UFORGE_DB_ADMIN_PASSWORD}
+		# echo "DROP DATABASE oar;" | mysql -u${UFORGE_DB_ADMIN_LOGIN} -p${UFORGE_DB_ADMIN_PASSWORD}
+		# echo "DROP DATABASE syncope;" | mysql -u${UFORGE_DB_ADMIN_LOGIN} -p${UFORGE_DB_ADMIN_PASSWORD}
+		# echo "DROP DATABASE uauthdb;" | mysql -u${UFORGE_DB_ADMIN_LOGIN} -p${UFORGE_DB_ADMIN_PASSWORD}
+		# cd /tmp/USER_DATA
+		# mysql -u${UFORGE_DB_ADMIN_LOGIN} -p${UFORGE_DB_ADMIN_PASSWORD} < db_backup_3.7.sql
+		# service mysql restart
+		# oar-database --setup (answer y to the question)
+		# /opt/opendj/bin/import-ldif -l uforge-export.ldif -n userRoot
+		# systemctl start oar-server
+		# service opendj start
+		if ( <target_db> != <target_ws> )
+			# /opt/UShareSoft/uforge/tools/update_scripts/uforge_update.sh 2>&1 | tee -a /tmp/USER_DATA/uforge_update_db_3.8.log
+		fi
+
+	#. Once the DB is reset, Tomcat has to be started. On <target_ws> run the following commands:
+
+	.. code-block:: shell
+
+		# service tomcat start
+		# /opt/UShareSoft/uforge/tools/update_scripts/uforge_update.sh 2>&1 | tee -a /tmp/USER_DATA/uforge_update_ws_3.8.log
+		# rm /tmp/USER_DATA/db_backup_3.7.sql
+		# rm /tmp/USER_DATA/uforge-export.ldif
+
+	#. If you have customized the UI you will need to follow these additional steps before migration to 3.8. This step applies to all the customization files in ``/var/opt/UShareSoft/uforge-client/gwt/uforge/templates`` (as decribed in), as well as ``config.xml``, ``forge-config.xml``, and css directory (in case of css customisation). Do the following on <target_ui>:
+
+		a) rsync the customised files from the UI node of the source UForge AppCenter to the UI node of the target AppCenter.
+		b) Edit file forge-config.xml, line
+
+			.. code-block:: shell
+
+			<c:uForgeUrl>http://10.2.1.11:8080/ufws/</c:uForgeUrl>
+
+		c) Replace the old web service node IP address with the IP address of the new web service node.
+		d) Launch the command 
+
+			.. code-block:: shell
+
+			/opt/UShareSoft/uforge-client/bin/uforge_ui_update.sh
+
+	#. If you detect an issue, please contact support@usharesoft.com with the following files:
+
+		* The standard output of the command
+		* The result of running the ``ifconfig`` command
+		* The ``/etc/hosts`` file
+		* The name of the current node
+
+
+

admin/en/source/pages/upgrade/redhat-mirror.rst

@@ -0,0 +1,60 @@
+.. Copyright 2017 FUJITSU LIMITED
+
+.. _redhat-mirror:
+
+Creating a Local Mirror for Red Hat Without Using a Satellite Server
+--------------------------------------------------------------------
+
+You can create a local mirror of the latest updates for Red Hat Enterprise Linux without using a satellite server. How this is set up will depend on your version of Red Hat Enterprise Linux.
+
+You can also refer to the Red Hat Knowledgebase solutions:
+	* `Migrating from RHN to RHSM in Red Hat Enterprise Linux <https://access.redhat.com/solutions/129723>`_.
+	* `How to register and subscribe a system to the Red Hat Customer Portal using Red Hat Subscription-Manager <https://access.redhat.com/solutions/253273>`_.
+
+Red Hat 5 and 6
+~~~~~~~~~~~~~~~
+
+1. Install Red Hat Enterprise Linux 5.0 or 6.0.
+
+2. Register the RH system running and register the system::
+
+	rhn_register command
+
+3. Migrate your subscription tool, RHN to RHSM, execute the following two commands:
+
+.. code-block:: shell
+
+	yum install subscription-manager-migration subscription-manager-migration-data
+	rhn-migrate-classic-to-rhsm
+
+4. Install your web server::
+
+	yum install httpd
+ 
+5. Create ``/var/www/html/RHEL/6/X86_64/``.
+6. Open port ``80``.
+
+7. Create a local mirror following the procedure described on the `Red Hat Knowledgebase <https://access.redhat.com/solutions/23016>`_.
+
+8. Add RedHat Enterprise Linux to your AppCenter. For detailed instructions, refer to :ref:`populate-rhel`.
+
+Red Hat 7
+~~~~~~~~~
+
+1. Install Red Hat Enterprise Linux 7.0 as any other installation.
+
+2. Register and subscribe your system to the Red Hat Customer Portal using Red Hat Subscription-Manager. Run the subscription manager with the RH Custom credential::
+
+    subscription-manager register –username –password –auto-attach
+
+3. Install your web server::
+
+	yum install httpd
+
+4. Create ``/var/www/html/RHEL/6/X86_64/``.
+
+5. Open port ``80``.
+
+6. Create a local mirror following the procedure described on the `Red Hat Knowledgebase <https://access.redhat.com/solutions/23016>`_.
+
+7. Add RedHat Enterprise Linux to your AppCenter. For detailed instructions, refer to :ref:`populate-rhel`.

admin/en/source/pages/upgrade/retrieve-data.rst

@@ -0,0 +1,66 @@
+.. Copyright 2017 FUJITSU LIMITED
+
+.. _retrieve-data:
+
+Retrieving Data from UForge
+---------------------------
+
+Before retrieving data from resellers.usharesoft.com using the lftp command from a UForge instance do the following:
+
+	1. Verify if the UForge instance is running in a virtualized infrastructure with security rules by default (AWS, OpenStack, ...). Ports 20, 21 (as well as 22 for SSH) must be allowed for outgoing traffic.
+
+	2. Due to the new proxy mechanism you must run::
+
+		export ftp_proxy="" 
+
+	This ensures that squid does not interfere with ftp transfer.
+
+.. _send-request:
+
+Sending a Request to UForge
+---------------------------
+
+As the UForge Web Services are RESTful, clients communicate via the standard HTTP(S) protocol. That means you can easily construct request URLs that will work on the command line and in your code.
+
+All UForge requests (with some exceptions) require authentication information as part of the request. There are several ways to communicate with UForge:
+
+	* Using API keys – A public and secret key is used to construct the URL.  This URL will contain public key and a signature that authenticates the request.
+	* Basic Authentication – Where the login name and password are provided in the requesting HTTP(S) headers.
+	* Custom – UForge provides AuthN and AuthZ modules that can be customized to provide other authentication mechanisms (refer to Customizing UForge Authentication for SSO).
+
+All request URLs start with the hostname of where UForge is running, the port where UForge is listening for incoming requests, the service name and version number. This is known as the BASE URL. 
+
+Even though UForge accepts HTTP requests, it is highly recommended for security reasons that HTTPS requests be used. HTTP requests should only be used for debugging purposes. Sensitive information will be exposed using HTTP.  
+
+UForge expects certain headers containing authentication information to be present as part of the URL request. UForge also accepts other header information, for example, to specify response content type and caching.
+
+The following is an example of a request sent to a UForge AppCenter with hostname 10.0.0.20 using cURL to get the user ``myUser``. Note that basic authentication is used for clarity.
+
+.. code-block:: shell
+
+	$ curl "http://10.0.0.20:9090/ufws/users/myUser" -H "Authorization: Basic myUser:password" -H "Accept: application/xml" -v | tidy -xml -indent -quiet
+
+		* About to connect() to 10.0.0.20 port 8080 (#0)
+		* Trying 10.0.0.20... connected
+		* Connected to 10.0.0.20 (10.0.0.20) port 8080 (#0)
+		> GET /ufws/users/myUser HTTP/1.1
+		> User-Agent: curl/7.19.7 (universal-apple-darwin10.0) libcurl/7.19.7 OpenSSL/0.9.8r zlib/1.2.3
+		> Host: 10.0.0.20:8080
+		> Accept: application/xml
+		>
+
+		< HTTP/1.1 200 OK
+		< X-Powered-By: Servlet/2.5
+		< Server: Sun GlassFish Enterprise Server v3.1.2
+		< Last-Modified: Thu, 08 Aug 2013 19:52:13 GMT
+		< ETag: "80f76a81b033572861260548dd748bb3"
+		< Content-Type: application/xml
+		< Transfer-Encoding: chunked
+		< Date: Thu, 21 Jul 2011 17:02:10 GMT
+		<
+
+		* Closing connection #0
+		<?xml version="1.0" encoding="utf-8" standalone="yes"?>
+		<user>
+		...omitted for clarity
+		</user>

admin/en/source/pages/upgrade/uforge-downgrade.rst

@@ -0,0 +1,14 @@
+.. Copyright 2017 FUJITSU LIMITED
+
+.. _uforge-downgrade:
+
+Going Back to a Previous Version of a UForge Deployment
+-------------------------------------------------------
+
+.. note:: Using ``yum downgrade`` to return to a previous version of UForge is not supported.
+
+Even though the ``yum downgrade`` command works from a packaging perspective, it will not roll back possible changes done to the database (especially the database schema).
+
+Moreover, there are additional factors that may lead to fatal errors, including configuration or properties files which are not considered by ``yum downgrade``, or possible changes of users and their permissions on the file system.
+
+If you need to downgrade a UForge deployment to a previous version, you should create a snapshot of your machine prior to the upgrade.