Mascot: The trusted reference standard for protein identification by mass spectrometry for 25 years

Updating and upgrading to Mascot Server 2.4

Thank you for ordering a Mascot version update and/or Mascot upgrade to use additional processors.

For the correct update or upgrade procedure, please choose from the options, below. If none of these apply, email support@matrixscience.com for more specific advice. In all cases, additional information can be found in the Installation & Setup Manual on the Mascot 2.4 program disk (manual.pdf).

If updating and upgrading:

Towards the end of the installation, you will be asked to register your Mascot 2.4 product key to obtain a licence file. This product key can be found on a sticker on the CD case or may have been sent by email. A licence file will be returned by email, and must be saved to mascot/config/licdb. Important: If you want to make a trial installation, do not register using your permanent Mascot 2.4 product key. Email support@matrixscience.com to request a 14 day temporary licence key

  1. Updating Mascot Server to version 2.4 on the current hardware
  2. Updating Mascot Server to version 2.4, while migrating to new hardware
  3. Upgrading Mascot Server to use additional processors on the current hardware
  4. Upgrading Mascot Server to use additional processors, while migrating to new hardware
  5. Upgrading Mascot Server to use additional processors while converting to a cluster but keeping the current hardware as the master node
  6. Upgrading Mascot Server Cluster to use the processors on additional search nodes
  1. Updating Mascot Server to version 2.4 on the current hardware

    Linux:

    1. The update procedure is described in Chapter 2 of the Installation & Setup Manual
    2. If updating Perl, do this before updating Mascot. Perl 5.14 is recommended, Perl 5.8, 5.10, and 5.12 are also supported. An installer for ActivePerl 5.14 is included on the program disk.
    3. You might wish to make a backup of the existing files before they are overwritten. All configuration files in the config directory apart from mascot.dat and the security settings will be overwritten by new files. All results files and sequence databases apart from SwissProt will be retained. The installation script will update mascot.dat by adding new options, but will retain all existing sequence database configuration settings and other options.

    Windows:

    1. Do not uninstall the old version of Mascot. Just run the 32-bit or 64-bit setup as described in Chapter 3 of the Installation & Setup Manual
    2. If updating Perl, do this before updating Mascot. Perl 5.14 is recommended, Perl 5.8, 5.10, and 5.12 are also supported. An installer for ActivePerl 5.14 is included on the program disk. You cannot perform single-step updates for ActivePerl. You must uninstall the old version before installing the new one. As a precaution, it is also worth deleting the Perl application directory after the uninstall step and re-booting.
    3. If any files from the previous version of Mascot have been modified, they will be moved to a folder under the main Mascot folder called _install_backup.

  2. Updating Mascot Server to version 2.4, while migrating to new hardware

    The migration procedure is as follows. If you do not wish to transfer your old searches, skip steps 4 – 6

    1. Install Mascot on the new system by following the instructions in Chapter 2 (Linux) or Chapter 3 (Windows) of the Installation & Setup Manual
    2. Towards the end of the installation, before trying to register the 2.4 product key, copy your original licence file to the Mascot config directory (this is a small text file called mascot.license in the Mascot config directory on the old server).
    3. Ensure everything is working correctly. Run a couple of test searches from a web browser on a different PC and make sure you can view the result reports.
    4. Copy all your search result files from the old system. That is, all the "daily" directories, such as 20120630, in mascot/data. Do not copy mascot/data/test or, if the old system was Mascot 2.3, mascot/data/cache. Do not copy across the files in mascot/data itself.
    5. Copy over mascot/data/mascot.job, replacing the file on the new system (this file contains the last job number).
    6. Copy over the search log (mascot/logs/searches.log), replacing the file on the new system. Check you can open old search results using the links in the search log.
    7. Mascot must then be deleted or uninstalled from the old system.

    Migrating sequence databases

    If you had only a few, public databases active on your old server, it is easiest to select them from the predefined database definitions in the new Mascot Database Manager. This means that the configurations will be kept up-to-date automatically and it is very easy to schedule automatic updating of the database files. If you had a large number of active databases on your old server that you had configured manually, you may prefer to copy across the files and configuration information. The procedure is as follows:

    1. After updating to version 2.4, do not run Database Manager.
    2. Copy the sequence database directories and files to the new system.
    3. If any databases had taxonomy defined, and the taxonomy files (in the taxonomy directory) are newer than those on the new system, copy these files across.
    4. Make a back-up copy of mascot.dat on the new system, just in case.
    5. In a text editor, open the old and new mascot.dat files. Make sure you are working with the latest files, and not some backup (e.g. mascot.dat.34).
    6. Copy the following sections from the old file to the new, replacing the corresponding sections in the new file:
      • Databases
      • PARSE
      • WWW
      • Taxonomy_n (where n is a number from 1 upwards)
      Each section starts with the keyword above and ends with word end. Lines starting with # are comments.
    7. If the paths to either the program files or the database files have changed, use search and replace to update the paths. Make sure you don’t accidentally change text in some other part of mascot.dat
    8. Double check your changes and save the new file.
    9. Carefully read the help page for Mascot Database Manager, then start it for the first time.
    10. For most of your old database definitions, select Keep as Custom. In some cases, Database Manager will recognise that an old definition is very similar to one of the new, predefined database definitions, and suggest that it be synchronised. If the identification was correct, then best to select Synchronise.
    11. Before you can enable automatic updating of the migrated database files, you will need to edit the definition(s) in Database Manager and enter the download URL(s) from the Mascot 2.3 database update script (or whatever update mechanism was used on the old system).

  3. Upgrading Mascot Server to use additional processors on the current hardware

    Mascot Server on a single PC (SMP):

    1. Register the new product key (Database Status; Licence Info; Register a new product key). A licence file will be returned by email. Save this to mascot/config/licdb
    2. Go to the Database Status page and verify that the number of processors shows the correct, new value.
    3. The number of threads displayed for each active database should be -1, which means this setting is auto-determined. If the number of threads for a database has been specified as a fixed number, you may or may not wish to change this in view of having more processors available (Configuration Editor; Database Manager).

    Mascot Server Cluster:

    1. If you need to add new search nodes, you are in the wrong section. Refer to Upgrading Mascot Server cluster to use the processors on additional search nodes
    2. Register the new product key (Database Status; Licence Info; Register a new product key). A licence file will be returned by email. Save this to mascot/config/licdb
    3. In the cluster section of mascot.dat, the number of processors in SubClusterSet 0 should be set to -1 (automatic). If it is a fixed number, you will need to change this to -1 or to the new number of processors.
    4. Re-start the Mascot Service (Windows) or kill and re-start ms-monitor.exe (Linux).
      5. Go to the Database Status page and verify that the number of processors shows the new, correct value.

  4. Upgrading Mascot Server to use additional processors, while migrating to new hardware

    This procedure can also be used when migrating a Mascot Server 2.4 installation to new hardware without any update or upgrade. Before commencing, contact support@matrixscience.com to request a new product key

    If you do not wish to transfer your old searches, skip steps 4 – 6

    1. Install Mascot on the new system by following the instructions in Chapter 2 (Linux) or Chapter 3 (Windows) of the Installation & Setup Manual
    2. If you are also updating to version 2.4, towards the end of the installation, before trying to register the 2.4 product key, copy your original licence file to the Mascot config directory (this is a small text file called mascot.license in the Mascot config directory on the old server).
      OR
      If already on version 2.4, register the new product key (Database Status; Licence Info; Register a new product key). A licence file will be returned by email. Save this to mascot/config/licdb
    3. Ensure everything is working correctly. Run a couple of test searches from a web browser on a different PC and make sure you can view the result reports.
    4. Copy all your search result files from the old system. That is, all the "daily" directories, such as 20120630, in mascot/data. Do not copy mascot/data/test or mascot/data/cache. Do not copy across the files in mascot/data itself.
    5. Copy over mascot/data/mascot.job, replacing the file on the new system (this file contains the last job number).
    6. Copy over the search log (mascot/logs/searches.log), replacing the file on the new system. Check you can open old search results using the links in the search log.
    7. Mascot must then be deleted or uninstalled from the old system.

    Migrating sequence databases:

    If you had only a few, public databases active on your old server, it is easiest to select them from the predefined database definitions in the new Mascot Database Manager. This means that the configurations will be kept up-to-date automatically and it is very easy to schedule automatic updating of the database files. If you had a large number of active databases on your old server that you had configured manually, you may prefer to copy across the files and configuration information. The procedure is as follows:

    If updating to version 2.4, or already on 2.4 but Database Manager has never been run, the procedure can be found here.

    If already on version 2.4, and Database Manager was being used on the old system:

    1. Copy the sequence database directories and files to the new system.
    2. If any databases had taxonomy defined, and the taxonomy files (in the taxonomy directory) are newer than those on the new system, copy these files across.
    3. Copy these files from under the Mascot directory on the old installation:
      • the directory config/db_manager/public plus all the files it contains
      • config/db_manager/global.conf
      • config/db_manager/configuration.xml
    4. If the paths to either the program files or the database files have changed, you’ll need to edit the following configuration files. Before editing a file, make a backup in some other directory.
      • If you have defined database update schedules, copy the entries in the Cron section in the old mascot.dat file to the new mascot.dat file, and fix the paths to dbman_add_task.pl and dbman_process_tasks.pl to point to the corresponding scripts in the new installation.
      • In global.conf, change the setting sequence directory under [default directories] to point to the new sequence directory.
      • In configuration.xml, do a global search and replace from the old sequence directory to the new sequence directory. The elements to target are msgd:current_path and msgd:incoming_path under msgd:databases. If you’ve set up sequence databases outside the Mascot sequence directory, you need to manually inspect the paths under msgd:databases and edit as necessary.
      • In configuration.xml, do a global search and replace from the old UniGene directory to the new UniGene directory. The elements to target are msgd:path under msgd:unigene_entries.
      • In configuration.xml, delete <msgd:mascot_dat_md5>, </msgd:mascot_dat_md5>, and everything in between.
      • Run Database Manager. It will detect that configuration.xml doesn’t match mascot.dat anymore. Click on Fix mascot.dat.

  5. Upgrading Mascot Server to use additional processors while converting to a cluster but keeping the current hardware as the master node

    Linux:

    1. If you are also updating to version 2.4, follow Updating Mascot Server to version 2.4 on the current hardware. Make sure you choose to configure as a cluster at step 4 of the installation script.
      OR
      If already on version 2.4, register the new product key (Database Status; Licence Info; Register a new product key). A licence file will be returned by email. Save this to mascot/config/licdb
    2. Kill ms-monitor.exe.
    3. If already on version 2.4, edit the cluster section of mascot.dat to enable cluster mode. In the cluster section of mascot.dat, the number of processors in SubClusterSet 0 should be set to -1 (automatic). If it is a fixed number, you will need to change this to -1 or to the new number of processors.
    4. Create a nodelist.txt file as described in Chapter 11 of the Installation & Setup Manual (page 201).
    5. The operating system on each search node must be configured exactly as described in Chapter 11. For example, it must be possible for the master node to communicate with each search node using ssh with key based authentication.
    6. Start ms-monitor.exe.

    Windows:

    1. If you are also updating to version 2.4, follow Updating Mascot Server to version 2.4 on the current hardware. Make sure you choose to configure as a cluster when that stage of the setup Wizard is reached.
      OR
      If already on version 2.4, register the new product key (Database Status; Licence Info; Register a new product key). A licence file will be returned by email. Save this to mascot/config/licdb
    2. If already on version 2.4, re-run setup, choose Change, and choose to configure as a cluster when that stage of the setup Wizard is reached.
    3. The operating system on each search node must be configured exactly as described in Chapter 11 of the Installation & Setup Manual.

  6. Upgrading Mascot Server Cluster to use the processors on additional search nodes
    1. If you are also updating to version 2.4, follow Updating Mascot Server to version 2.4 on the current hardware.
      OR
      If already on version 2.4, register the new product key (Database Status; Licence Info; Register a new product key). A licence file will be returned by email. Save this to mascot/config/licdb
    2. Stop the Mascot Service (Windows) or kill ms-monitor.exe (Linux).
    3. In the cluster section of mascot.dat, the number of processors in SubClusterSet 0 should be set to -1 (automatic). If it is a fixed number, you will need to change this to -1 or the to new number of processors.
    4. Edit mascot/config/nodelist.txt to add new definitions for additional search nodes by analogy with existing definitions.
    5. The operating system on each new search node must be configured exactly as described in Chapter 11 of the Installation & Setup Manual.
    6. Start the Mascot Service (Windows) or start ms-monitor.exe (Linux).