Migrating to a 5.2/6.1 Multihome Configuration File

[#1]

Version

Cb Response 5.2.x, 6.0, 6.1.x

Topic

The multihome file has been heavily modified to make it easier to setup and migrate changes between versions. This guide details how to migrate to a 5.2/6.1 multihome file from a prior version.

Steps

Master

1. Rename cb.conf to prevent duplicate includes

   mv /etc/cb/nginx/conf.d/cb.conf /etc/cb/nginx/conf.d/cb.conf.bak5.2

   Warning: There should only be cb.conf and http.conf files with the .conf extension in /etc/cb/nginx/conf.d/ otherwise services won't start or changes will need to be made following an upgrade

2. Rename the pre 5.2 multihome file
   

   mv /etc/cb/nginx/conf.d/cb-multihome.conf /etc/cb/nginx/conf.d/cb-multihome.conf.bak5.1

3. Copy the 5.2 multihome file example
   

   cp /etc/cb/nginx/conf.d/cb.multihome.conf.example /etc/cb/nginx/conf.d/cb.conf

   Note: the new multihome configuration file has changed names from cb-multihome.conf to cb.conf

4. Change these lines in the multihome configuration file /etc/cb/nginx/conf.d/cb.conf under the UI section:
   

   # This server configuration is used for CB Enterprise Server's Web UI

   listen [::]:443 ssl ipv6only=off;

   To
   

   listen [::]:8443 ssl ipv6only=off;

5. Redirect port 80 to 8443 (Optional)
   

   Note: Only perform this step if port 80 is open and redirection to HTTPS IS desired

   1. Backup the http.conf file before making changes:
      

      cp /etc/cb/nginx/conf.d/http.conf /etc/cb/nginx/conf.d/http.conf.original

   2. Edit this line in the /etc/cb/nginx/conf.d/http.conf configuration file to redirect port 80 to port 8443 (HTTPS):
      

      return         301 https://$host$request_uri;

      To
      

      return         301 https://$host:8443$request_uri;

      Warning: while making these changes, keep the indentation correct

      Note that in the variable $request_uri it's uri, not url

6. Using a signed cert (Optional)
   1. Comment out these lines from multihome configuration file /etc/cb/nginx/conf.d/cb.conf:
      

      include /var/cb/nginx/props/nginx.runtime.ssl_certificate.prop;
      include /var/cb/nginx/props/nginx.runtime.ssl_certificate_key.prop;

      To:
      

      #include /var/cb/nginx/props/nginx.runtime.ssl_certificate.prop;
      #include /var/cb/nginx/props/nginx.runtime.ssl_certificate_key.prop;

   2. Locate the ssl_certificate and ssl_certificate_key from the old configuration file:
      

      grep ssl_certificate  /etc/cb/nginx/conf.d/cb-multihome.conf.bak5.1

   3. Add these below the the commented signed cert lines in the multihome configuration file /etc/cb/nginx/conf.d/cb.conf. Example:
      

      ssl_certificate /etc/cb/certs/mycert.crt;
      ssl_certificate_key /etc/cb/certs/mycert.key;

7. Commit changes
   1. Run this command if nginx failed to start:
      

      service cb-nginx restart

   2. Otherwise follow the normal upgrade procedure which will restart services as part of the upgrade process
8. If cb-nginx won't start, check the bottom of /var/log/cb/nginx/startup.log for errors:
   

   tail /var/log/cb/nginx/startup.log

Warning: There are additional changes that need to be made if you are using the multihome configuration for the first time. Please follow the additional steps provided here: Multihome Configuration Troubleshooting

Minions

Minions should use the default /etc/cb/nginx/conf.d/cb.conf configuration since the UI is accessed though the master.

1. If nginx doesn't start on the minions, rename the pre 5.2 multihome file:
   

   mv /etc/cb/nginx/conf.d/cb-multihome.conf /etc/cb/nginx/conf.d/cb-multihome.conf.bak5.1

2. If cb-nginx won't start, check the bottom of /var/log/cb/nginx/startup.log for errors:
   

   tail /var/log/cb/nginx/startup.log