Filr Upgrade Pre-Flight checklist

Although in most cases these checks are not required, it would be advisable to verify these files so the upgrade can go more smoothly and known issues can be avoided whenever possible.

This TID is a work in progress, does not pretend to be complete and it is written in the assumption that the Filr environment, especially the SQL environment is unaltered compared to a default Filr installation.

This TID is focusing on a Cluster setup, as this is the setup where a small failure can have the largest impact, but several items can be of value for a large or small setup too.

Before upgrading the Filr appliance(s), while these are still running the previous release code, verify if the contents of these files are reflecting the current setup or configuration.

FYI:

• To make sure this is a readable TID only the most critical values to allow a successful upgrade are listed, but do not refrain from verifying all other settings too.
• Variables, that may differ from the default and that are specific to the Filr setup are listed as [value]

For a Cluster node, with NFS for /vashare, High-Availibility Search with 2 search appliances and a MySQL database and no port redirection configured:

/etc/sysconfig/novell/NvlVAinit

SERVICE_CONFIGURED="yes"
CONFIG_VAINIT_HOSTNAME="[hostname.dns.suffix]"
CONFIG_VAINIT_SEARCH_DOMAINS="[search.dns.suffxes as required]"
CONFIG_VAINIT_IPADDRESS="[assigned.ip.address]"
CONFIG_VAINIT_NETWORK_MASK="[subnet.mask]"
CONFIG_VAINIT_GATEWAY="[gateway.ip.address]"
CONFIG_VAINIT_DNS_SERVER="[IP address(es) of the DNS server(s)]"
CONFIG_VAINIT_NTP_SERVER="[ntp.server(s)]"
CONFIG_VAINIT_STORAGE_TYPE="device"
CONFIG_VAINIT_DEVICE_STORAGE="type:existing drive:sdb name:sdb1 format:MSDOS fs:[chosen.filesystem (in general ext3)]" (!!)
CONFIG_VAINIT_SHARED_STORAGE_TYPE="nfs"
CONFIG_VAINIT_SHARED_NFS_SERVER_HOST="[dns name or IP address of the NFS server]"
CONFIG_VAINIT_SHARED_NFS_REMOTE_DIR="[nfs/share/path]"

(!!) In case this value reads "type:uninitialized drive:sdc size:* format:ext3" then the value should be set to CONFIG_VAINIT_DEVICE_STORAGE="type:existing drive:auto name:auto format:auto"


/filrinstall/configurationDetails.properties

type=large    (also valid for a cluster)

/filrinstall/installer.xml

<Host ajpPort="8009" ajpPortEnabled="true" apr="true" forceSecure="true" keystoreFile="" listenPort="8080" listenPortDisabled="8080" listenPortEnabled="true" name="[name of the appliance or the load balancer]" port="80" portDisabled="8080" portRedirect="false" proxyhostname="" proxyport="80" secureListenPort="8443" securePort="443" shutdownPort="8005"/>

<JavaVirtualMachine ms="[value of the JVM min setting]" mx="[value of the JVM max setting" ss=""/>

<Config id="Installed" type="MySql">
            <Resource driverClassName="com.mysql.jdbc.Driver" for="icecore" password="[encrypted password]" url="jdbc:mysql://[name or ip of the mysql host]:3306/[Filr's MySQL Database]?useUnicode=true&amp;amp;characterEncoding=UTF-8" username="[MySQL user used by Flr]"/>

<Lucene luceneLocation="high availability">
        <Resource lucene.index.hostname="[dns name or ip of the first lucene]" lucene.max.booleans="10000" lucene.max.ha.search.nodes="100" lucene.merge.factor="10" lucene.rmi.port="1199" lucene.rmi.service="" lucene.server.login="lucene service" lucene.server.password="[Encrypted Password]" lucene.server.port="1188">

<HASearchNode ha.service.name="[how the first lucene is listed]" ha.service.title="[Description of first lucene]" ha.service.hostname="[dns name or IP of the first lucene]" ha.service.rmi.port="1199"/>
<HASearchNode ha.service.name="[how the second lucene is listed]" ha.service.title="[Description of second lucene]" ha.service.hostname="[dns name or IP of the second lucene]" ha.service.rmi.port="1199"/>

<Clustered cacheGroupAddress="232.0.0.1" cacheGroupPort="4446" cacheService="" cachingProvider="memcached" enable="true" jvmRoute="worker1" memCachedAddress="" memcachedAddresses="[dns name or IP of first lucene]:11211 [dns name or IP of second lucene]:11211"/>

<Encryption algorithm="PBEWITHSHA256AND128BITAES-CBC-BC"/>

/filrinstall/db/mysql-liquibase.properties

referencePassword==[encrypted password]=
referenceUrl=jdbc:mysql://[name or IP of the MySQL server]:3306/[Filr's database]?useUnicode=true&amp;characterEncoding=UTF-8
url=jdbc:mysql://[name or IP of the MySQL serfver]:3306/filr?useUnicode=true&amp;characterEncoding=UTF-8
password==[encrypted password]=
referenceUsername=[Filr's MySQL User]
username=[Filr's MySQL User]

/opt/novell/filr/apache-tomcat/webapps/ssf/WEB-INF/classes/config/ssf-ext.properties

user.pwdenc.default=PBEWITHSHA256AND128BITAES-CBC-BC
data.root.dir=/vashare/filr
data.simplefilerepository.root.dir=/vashare/filr
data.jackrabbitrepository.root.dir=/vashare/filr
data.extension.root.dir=/vashare/filr
data.archivestore.root.dir=/vashare/filr
data.luceneindex.root.dir=/vashare/filr
cache.file.store.dir=/vashare/filr/cachefilestore
data.databaselogs.dir=/vashare/filr/databaselogs
temp.dir=/vashare/filr/temp
filtering.failed.dir=/vashare/filr/filteringfailed
fi.work.dir=/vashare/filr/fi/work

/opt/novell/filr/apache-tomcat/webapps/ssf/WEB-INF/context/applicationContext-ext.xml

<bean id="luceneSessionFactory" class="com.novell.teaming.search.ha.HALuceneSessionFactory" depends-on="sPropsUtil">
        <property name="nodes">
            <list>
                <bean class="com.novell.teaming.search.ha.HALuceneNode">
                    <property name="name">
                        <value>[How the first Lucene is listed]</value>
                    </property>
                    <property name="sessionFactory">
                        <bean class="com.novell.teaming.search.remote.RemoteLuceneSessionFactory">
                            <property name="indexHost">
                                <value>[dns name or IP of the first Lucene]</value>
                            </property>
                            <property name="rmiPort">
                                <value>1199</value>
                            </property>
                        </bean>
                    </property>
                    <property name="indexNodeManager">
                        <ref bean="indexNodeManager"/>
                    </property>
                    <property name="journalManager">
                        <ref bean="searchJournalManager"/>
                    </property>
                </bean>
                <bean class="com.novell.teaming.search.ha.HALuceneNode">
                    <property name="name">
                        <value>[How the second Lucene is listed]</value>
                    </property>
                    <property name="sessionFactory">
                        <bean class="com.novell.teaming.search.remote.RemoteLuceneSessionFactory">
                            <property name="indexHost">
                                <value>[dns name or IP of the second Lucene]</value>
                            </property>
                            <property name="rmiPort">
                                <value>1199</value>
                            </property>
                        </bean>
                    </property>
                    <property name="indexNodeManager">
                        <ref bean="indexNodeManager"/>
                    </property>
                    <property name="journalManager">
                        <ref bean="searchJournalManager"/>
                    </property>
                </bean>
            </list>
        </property>
        <property name="selector">
            <bean class="com.novell.teaming.search.ha.DefaultSelector"/>
        </property>
    </bean>
</beans>

/vashare/filr/conf/sec.properties
/vastorage/filr/conf/sec.properties

Although this file will not be part of the vaconfig.zip, in a cluster none of the Filr nodes should have this file on /vastorage as all nodes should be using the same encryption / decryption key stored on the /vashare.

Make sure that the correlating Filr version license key file is installed and no longer the Filr license file of the previous release or even Novell Filr1.0.

After all these files were verified, and are sure to contain the required cluster related information, it is required to regenerate a /vastorage/conf/vaconfig.zip (after creating a backup copy) using the following command:

python /opt/novell/base_config/zipVAConfig.py

In some rare cases, especially in Filr instances that have been running and been upgraded from Novell Filr 1.0, Novell Filr 1.0.1 or Novell Filr 1.1 we have observed some configuration files that were not or incorrectly updated over time.
This could cause that during the upgrade the /vashare is not mounted and because of that the encryption key to be regenerated causing the incorrect decryption of the stored passwords in the configuration and several other fatal phenomena.

An other observed phenomena is that when the Filr node (even when only temporarily) was reconfigured to use Basic for the WebDAV authentication method, the password encryption algorithm changed in the file that sets it during the upgrade.
This caused the inability of users to log in after the upgrade.

In each case this resulted in very unwanted, erroneous configurations that can stay unnoticed until or after the systems were upgraded.

It depends on what patch level the systems were when these administrative changes that trigger these unwanted effects were performed if the Filr systems are affected or not.
This however makes it near to impossible to determine which systems are affected, therefor we suggest to check and verify the files mentioned and updating the vaconfig.zip before attempting the upgrade to increase the chance of a successful update to Filr 2.0. 

For a small Filr setup, in addition check TID 7016687


If, during the upgrade of the first node errors occur during the database update, that looks similar to:

Cannot find net folder config that this non-top net folder [number] belongs to

Please contact Technical Services so they can assist you in this matter.

In order to allow a usable and manageable virtual disk in a VMware environment, make sure that the second hard disk of the appliance that requires to be upgraded is configured to be "independent" and "Persistent" before starting the copy of the virtual disk file(s).

Additional information regarding a couple files:
[How the * Lucene is listed] refers to how that Lucene / Search Appliance is listed In the Search Appliance configuration Page of the Filr, reachable via port 9443 > Novell Filr Appliance Configuration > Search appliance.


/etc/sysconfig/novell/NvlVAinit

• The NTP server entries are fairly critical to be correct, as Filr relies heavily on a correct timesync between all appliances that build up the Filr cluster environment as well with the back-end servers.
• In case of a CIFS shared storage setup for /vashare, there should not be any NFS related entries populated and the CIFS related entries should look like:

CONFIG_VAINIT_SHARED_CIFS_SERVER_FOLDER="\\[dns name or IP of the CIFS server]\[share]"
CONFIG_VAINIT_SHARED_CIFS_ADMIN="[User Name]"
CONFIG_VAINIT_SHARED_STORAGE_TYPE="cifs"

In addition, there should be a /etc/opt/novell/base/.smbcredentials which should contain a username= and password= entry

/filrinstall/installer.xml

• The entries related to the network can not cause an upgrade failure, but can cause an annoyance after the upgrade. If port redirection is enabled, the network entry would look like:

 <Host ajpPort="8009" ajpPortEnabled="false" apr="false" forceSecure="true" keystoreFile="" listenPort="8080" listenPortDisabled="8080" listenPortEnabled="true" name="[name of the appliance or the load balancer]" port="80" portDisabled="0" portRedirect="true" proxyhostname="" proxyport="80" secureListenPort="8443" securePort="443" shutdownPort="8005"/>

• The entries related to the JVM might cause some failures during the upgrade, but mostly just an annoyance after the upgrade. However, make sure to configure the newly deployed Virtual Machine with at least the same amount of RAM compared to the previous appliance. Keep in mind not to decrease the RAM.
• In case you doubt the SQL password, it can be re-entered in clear text.
• If the Lucene luceneLocation is not stored as high availability, the upgrade will succeed, but with only a single Search Appliance connected. It is recommended to have all Search appliances to be connected during the upgrade so they can be updated and re-indexed in the same manner.
• In the Clustered cacheGroupAddress section the memcachedAddress value might point to the Filr appliance(s) ip addresse(s); In the course of Filr's lifespan a design change was made to transfer the memcached functionality to the less strained Search appliances. This changes was not made automatically for clusters that were configured before this design change and can be made -if desired- before or after the upgrade. When changing this to reflect the new design approach, make sure that the Search appliance is configured to start the mecached service, and that it's Firewall allows access to port 11211 alongside 1199.

/filrinstall/configurationDetails.properties

• In this file, there is also a configuration line that controls whether the local postfix mail server is used, or not (true or false) this has no influence on the end result for the upgrade itself, but when Filr was configured to use a remote, corporate mail server, this could be an annoyance when incorrect after the upgrade. If this value is set to true make sure there is an entry in the /filrinstall/installer.xml that looks like:

<Outbound allowSendToAllUsers="true" defaultTZ="[Configured TimeZone]" forceHTTPSLinks="[true or false]" fromEmailAddressOverride="" fromEmailAddressOverrideAll="false">
            <Resource mail.smtp.auth="true" mail.smtp.connectiontimeout="15000" mail.smtp.host="[smtp server ip or dns name]" mail.smtp.password="[some encrypted password]" mail.smtp.port="25" mail.smtp.sendpartial="true" mail.smtp.starttls.enable="false" mail.smtp.user="[configured mail user]" mail.smtps.auth="true" mail.smtps.connectiontimeout="15000" mail.smtps.host="[smtp server ip or dns name]" mail.smtps.password="[some encrypted password]" mail.smtps.port="25" mail.smtps.sendpartial="true" mail.smtps.starttls.enable="false" mail.smtps.user="[configured mail user]" mail.transport.protocol="smtp"/>

/filrinstall/db/mysql-liquibase.properties

• If you doubt the correctness of the passwords, you can enter the passwords in clear text, this will however required to replace the double equals sign ( == ) with a single ( = ) and removing the trailing one.

When upgrading the Filr appliance to a newer version, the procedure to do so for -up to and including- Filr 2.0 the procedure is to replace the first disk, with the operating system, only preserving the second disk that contains the /vastorage. When you had reconfigured the Filr so it was able to connect to NAS devices that only allowed NTLMv1, SMBv1 and /or required the workgroup= to be populated with the AD domain name, please be aware that these manually altered configuration files are not preserved and will be in a default state after the upgrade.
In addition, Filr 2.0 uses a seperate smb.conf /etc/opt/novell/filr/.smb/smb.conf