upgrading oXygen License Servlet

[JoergSachse]

Hello everyone,

I'm trying to automate the installation & upgrade process for the oXygen License Servlet using Ansible, because this is the standard procedure for documentation and disaster recovery at our company. This includes downloading and deploying a fresh WAR to Apache Tomcat 9 on Debian 10. During the upgrade deployment, the Tomcat server needs to be restarted and the Servlet loses all of the license information (as expected).

The page https://www.oxygenxml.com/doc/versions/ ... _server_wa says:

By default, the license server stores the statistics database and other data in the Java Servlet Container's temporary directory. If you are not using Apache Tomcat, this directory may be deleted when the server is stopped or restarted. However, you can set the oxygen.license.server.work.dir system property to specify a different path for the directory where the database is stored.

I've found databases in "/var/lib/tomcat9/work/Catalina/localhost/oXygenLicenseServlet/db/", but guessing from their filenames, they only contain log information. Also, there's a licence file at "/var/lib/tomcat9/work/Catalina/localhost/oXygenLicenseServlet/license.txt", but it contains a Machine signature that changes during WAR deployment. However, eeploying a new WAR seems to change the Machine Signature for the license server, so this file cannot be reused either.

My main questions are:

• Where exactly do I set the "oxygen.license.server.work.dir" parameter? Can you give me a canonical filepath?
• How can I make the Machine Signature persistent? Alternatively, where do I get the Machine signature so I can make the lisence into a template that can be used during deployment?
• Which files need to be backed up before upgrading to a new version of the License Servlet?

The page https://www.oxygenxml.com/doc/versions/ ... rvlet.html describes a manual process and thus cannot be used.

Any help is very much appreciated. If you need any more details, I'll do my best to provide them. Thank you and all the best,
Joerg

[mihai_coanda]

Hello,

The license binding process ensures only one server using this license key runs at once.
If you only upgrade an existing installation, on the same machine, by replacing the existing deployment the upgraded installation and continue to work with the current license key.

From what I understand you create a new machine for upgrades and disaster recovery that causes the previously activated license key to no longer work as it was bound to another server (the user database continues to be picked up even on other servers). In order to move the license key to a new machine, you will need to contact our sales department by email at salex@oxygenxml.com to deactivate the binding to the failed server ( the license key that you want deactivated should be mentioned in the email).


Where exactly do I set the "oxygen.license.server.work.dir" parameter? Can you give me a canonical filepath?

This parameter allows you to store the license server database and the activated license key to another directory, other than the default one which in your case is /var/lib/tomcat9/work/Catalina/localhost/oXygenLicenseServlet/. This should be used if the server container that you are using does not keep the data directory between restarts but that is not your case.



How can I make the Machine Signature persistent? Alternatively, where do I get the Machine signature so I can make the lisence into a template that can be used during deployment?

The Machine Signature is presented in the License Server UI so manual activation is required on new installations
The Machine Signature ties the license to a machine and deployment (file paths and ports are using when computing it) so it will not remain the same on another deployment by design, there is no way to force this persistence between deployments.



Which files need to be backed up before upgrading to a new version of the License Servlet?

The /var/lib/tomcat9/work/Catalina/localhost/oXygenLicenseServlet/ folder and all of its content should be backed up on upgrades and just copied at the same path to preserve the server configuration and state.


Regards,
Michael

[JoergSachse]

Hi Michael,

thank you for your help; I do understand that recovering on a fresh system will require support to do a reset of the license activation before deployment.

I followed your recommendation for the upgrading procedure (NOT "rebuild to recover" on another machine) and did:

Code: Select all

# stop tomcat9 service
sudo systemctl stop tomcat9.service

# backup folder and all of its content before update
sudo cp -r /var/lib/tomcat9/work/Catalina/localhost/oXygenLicenseServlet /tmp/

# download new WAR version
cd /tmp/
wget https://www.oxygenxml.com/InstData/LicenseServlet/oXygenLicenseServlet.war

# overwrite existing WAR with updated version
sudo cp oXygenLicenseServlet.war /var/lib/tomcat9/webapps/

# restore backup
sudo cp -r /tmp/oXygenLicenseServlet /var/lib/tomcat9/work/Catalina/localhost/

# reset permissions that were changed due to use of sudo
sudo chown -R tomcat.tomcat /var/lib/tomcat9/work/Catalina/localhost/oXygenLicenseServlet
sudo find /var/lib/tomcat9/work/Catalina/localhost/oXygenLicenseServlet -type f -exec chmod g+r \{\} \;
sudo find /var/lib/tomcat9/work/Catalina/localhost/oXygenLicenseServlet -type d -exec chmod g+rx \{\} \;

# start tomcat9 service
sudo systemctl start tomcat9.service

Apparently, the Machine Signature for my license server ("0RSq...6w==") doesn't change, which is a good sign. Also, the License server version is now stated as "23.1.2021030312" in the "Current Allocated Licenses" page. Before that, it was version "21.1.2019072215", so that's good, too.

Even though the initial issue is solved for me, please allow me one additional question: in the backup of "/var/lib/tomcat9/work/Catalina/localhost/oXygenLicenseServlet/", there's this subdirectory called "org/" that contains "*.java" and "*.class" files. I'm really not an expert on Java applications and Tomcat, but these look suspiciously like they could contain not only data but also code that belongs to the older version of the License Servlet WAR. Is it safe to use those older versions with the newer WAR?

Regards,
Joerg

[mihai_coanda]

Hello Joerg,

Those files are generated by Tomcat, being generated from Jsp files and Tomcat updates them on any change made to the .jsp file so keeping them should not represent an issue.
If you desire you can remove that folder when updating.

Regards,
Michael

[oxyfr]

Hello Joerg,

Please can you share your Ansible playbook for the license server?

[JoergSachse]

@oxyfr Yeah, sure, there you go:

Code: Select all

# The oXygen HTTP License Server Manager can be accessed at
# 'http://localhost:${installer:port}/', "admin" or "manager" credentials will
# be required for this task.
# From here you can perform various management tasks as viewing and changing the
# license the server dispatches and consult statistics about the licenses usage.

- name: install Apache Tomcat
  apt:
    name: "tomcat9"
    state: present
    autoclean: true
    autoremove: true
    install_recommends: false

# Do NOT use "restarted", it will screw up the installation!!!
- name: stop Apache Tomcat
  systemd:
    service: "tomcat9.service"
    state: stopped

# The INSTALL procedure is documented here:
# https://www.oxygenxml.com/doc/versions/23.1/ug-editor/topics/floating-license-servlet-setup.html#floating-license-servlet-setup__installation_steps_for_the_http_license_server_wa
# The manual UPGRADE procedure is documented here:
# https://www.oxygenxml.com/doc/versions/23.1/ug-editor/topics/upgrade-license-servlet.html
# Additional questions on automating upgrades have been answered by here:
# https://www.oxygenxml.com/forum/topic22511.html

- name: see if Servlet is already installed
  stat:
    path: "/var/lib/tomcat9/webapps/oXygenLicenseServlet.war"
  register: old_war

- name: create backup if oXygen License Servlet is already installed
  block:
    - name: find files to backup
      find:
        paths: "/var/cache/tomcat9/Catalina/localhost/oXygenLicenseServlet/"
        file_type: file
        recurse: true
      register: backup_files
    # https://docs.ansible.com/ansible/latest/collections/ansible/builtin/fetch_module.html
    - name: backup Oxygen data
      fetch:
        src: "{{ item.path }}"
        dest: "{{ playbook_dir }}/backups/license/{{ backup_timestamp }}/"
      loop: "{{ backup_files.files }}"
  when: old_war.stat.exists

- name: get available WAR checksum
  get_url:
    url: "https://www.oxygenxml.com/InstData/LicenseServlet/oXygenLicenseServlet.war"
    dest: "/tmp/"
  register: new_war

#The oXygen HTTP License Server has three levels of security
# * admin accounts - have the highest security clearance, having access all
#   administrative tasks, like configuring the license server's license.
# * manager accounts - have medium security clearance, having access only to the
#   initial page and report pages.
# * user accounts - are used only by the oXygen application to configure the
#   license using this HTTP/HTTPS server.
- name: template the tomcat users configuration out to the managed system
  template:
    src: "etc/tomcat9/tomcat-users.xml.j2"
    dest: "/etc/tomcat9/tomcat-users.xml"

- name: deploy application WAR from vendor
  copy:
    src: "/tmp/oXygenLicenseServlet.war"
    dest: "/var/lib/tomcat9/webapps/"
    owner: "tomcat"
    group: "tomcat"
    mode: "0640"
    remote_src: true
  when: ( not old_war.stat.exists ) or
        ( old_war.stat.checksum != new_war.checksum_src )

- name: restore backup
  copy:
    src: "{{ playbook_dir }}/backups/license/{{ backup_timestamp }}/{{ ansible_hostname }}/var/cache/tomcat9/Catalina/localhost/oXygenLicenseServlet/"
    dest: "/var/cache/tomcat9/Catalina/localhost/oXygenLicenseServlet/"
    owner: "tomcat"
    group: "tomcat"
    mode: "o+rwx,g+r"
  when: ( not old_war.stat.exists ) or
        ( old_war.stat.checksum != new_war.checksum_src )

- name: set Tomcat port to port 80
  xml:
    path: "/etc/tomcat9/server.xml"
    xpath: '/Server/Service[@name="Catalina"]/Connector'
    attribute: 'port'
    value: "80"

- name: add iptables rule
  iptables:
    action: append
    chain: INPUT
    comment: "Tomcat port"
    destination_port: "80"
    ip_version: "ipv4"
    jump: ACCEPT
    protocol: "tcp"
    state: present
    table: filter
  tags: [iptables]

- name: deploy Oxygen logrotate config
  copy:
    src: "etc/logrotate.d/oxygen"
    dest: "/etc/logrotate.d/oxygen"
    owner: "root"
    group: "root"
    mode: 0644

# Do NOT use "restarted", it will screw up the installation!!!
- name: start Apache Tomcat
  systemd:
    service: "tomcat9.service"
    state: started