Upgrade considerations for customized configuration files in the /etc directory

If you have modified any configuration file in the /etc directory and copied it to the /nsconfig directory, to maintain persistency, the Citrix ADC appliance creates a symlink in /etc pointing to the file in /nsconfig.

For example: /etc/httpd.conf -> /nsconfig /httpd.conf

A release package might contain its own version of the configuration files in the /etc directory. These configuration files include important updates that are required for the Citrix ADC appliance to properly function. Upgrading a Citrix ADC appliance to a release replaces the configuration files in the /etc directory with the configuration files containing the release updates.

Consider an example of a customized configuration file, example.conf, which is present in the /etc directory. The example.conf file is copied to the /nsconfig directory to maintain persistency. The Citrix ADC appliance creates a symlink in /etc pointing to the file in /nsconfig: /etc/example.conf -> / nsconfig /example.conf

Also, a release package includes its own version of example.conf, which contains important updates. The following behavior is observed when you upgrade the Citrix ADC appliance to the release:

Because the symlink /etc/example.conf is already present, the Citrix ADC appliance does not place the release package copy of the example.conf in the /etc directory during the upgrade process.

As the release package copy of example.conf contains important updates, the absence of it in the /etc directory can cause the Citrix ADC appliance to fail or to not properly function.

Steps to preserve upgrade changes and customization

To ensure that both release updates and your customizations are not lost, perform the following steps:

• Pre-upgrade steps:
  • Back up customized file before upgrade
    
  • Remove persistency of customized file before upgrade
    
• Post-upgrade steps:

  • Apply customizations to upgraded file and add persistency after upgrade
    

    Important:

    Do NOT directly replace your customized file in the /etc folder. Directly replacing a /etc file with the back-up customized file removes any release updates added to the file during the upgrade process.

Back up customized file before upgrade

Take a backup of the customized files present in the /nsconfig directory before upgrading the appliance.

Create a /var/nsconfig_backup directory and move the customized files to this directory. That is, move any files that you modified in the /etc directory and copied to /nsconfig by running the following command at the shell prompt:

mv /nsconfig/<filename> /var/nsconfig_backup/<!--NeedCopy-->

Example:

mv /nsconfig/httpd.conf /var/nsconfig_backup/<!--NeedCopy-->

Remove persistency of customized file before upgrade

Delete the /etc symlinks that are pointing to the /nsconfig files before upgrading the appliance.

1. Check the existing symlinks in the /etc directory by running the following command at the shell prompt:

   ls -la /etc<!--NeedCopy-->

2. Delete a /etc symlink pointing to a /nsconfig file by running the following command at the shell prompt:

   unlink /etc/<filename><!--NeedCopy-->

   Example:

   unlink /etc/httpd.conf<!--NeedCopy-->

3. Verify that the symlink is removed by running the following command at the shell prompt:

   cat /etc/<filename><!--NeedCopy-->

   Example:

   cat /etc/httpd.conf<!--NeedCopy-->

   This command does not display any content if the symlink is removed.

Apply customizations to upgraded file and add persistency after upgrade

If you have taken a backup of any modified /nsconfig config file to the /var/nsconfig_backup, do the following after upgrading the appliance:

1. Compare the file present in the /var/nsconfig_backup and the /etc directories. Manually add the appropriate changes to the /etc file already containing the release updates.

   Important:

   Directly replacing the /etc file with the /var/nsconfig_backup file removes any release updates added to the file during the upgrade process. This removal of updates can cause the related Citrix ADC functionalities to fail or to not work properly.

2. To maintain persistency, copy the updated file present in the /etc directory to the /nsconfig directory by running the following command at the shell prompt:

   cp /etc/<filename> /nsconfig/<!--NeedCopy-->

   Example:

   cp /etc/httpd.conf /nsconfig/<!--NeedCopy-->

3. Repeat the above two steps for each customized file present in the /var/nsconfig_backup directory.

4. Restart the appliance to put the changes into effect.