Installing OpticStudio with a Black USB network hardkey (server and client)

This article is intended to help those with a Black USB network licenses install the key server software, as well as configure client machines to locate and use the license. This article requires a basic understanding of IP addresses and firewalls. Additionally, you must have a working network. Zemax LLC cannot provide assistance with your network or firewalls. 

Authored By Alissa Wilczynski

Introduction

The Black USB network key is installed on a machine called the keyserver. It must be on the same network where client machines can reach it to use the Zemax license. OpticStudio clients must be told where to 'look' to find the key server by entering the server name into an XML configuration file.

NOTE:  Before continuing this article, you should be certain that you have a black USB license.


make sure you have black key

If you do not possess a black USB network license and your server uses a Red USB key or softkey network license instead (the key numbers are similar to L000001), refer to the following article: "How to configure the keyserver and clients for Zemax network licenses."

Configuring the keyserver

Before you get started configuring your keyserver, note the following: 

  • The server you are installing on needs to be available to the client machines whenever they launch Opticstudio. It can run on any 32-bit or 64-bit Windows XP / Server 2003 or later operating system. If you are going to run a copy of OpticStudio on the server as well, you need a 64 bit version of Server 2008 R2 Sp1 or Windows 7 Sp1, 8.1 or 10. If only used as a key server, 1GB of RAM and 200mb of available storage is all that is required. 
  • Multiple OpticStudio users are not supported on any single machine, as the licensing will only assign one license seat per machine. You may therefore run one OpticStudio user (or two instances of OpticStudio) on the server machine or any one client machine. 
  • The client machines must be able to ping the keyserver in order for license to be found.
  • The USB licenses work via ports 7001 and 7002 for communication by default. These port numbers were chosen because they are not normally used for any other purpose. 
  • Be aware the install process requires administrator rights.
  • Do not plug in your USB license until after the software install is complete. Also, if you have other Safenet/ Gemalto keys for any other software installed, we recommend you temporarily remove these keys during the installation. (They may be replaced once installation is complete). 

After you have read the above information, you may begin configuring the software on the key server machine. To do this, follow the instructions below.  

  1. Download the "Sentinel Protection Installer" application on the keyserver machine. It is available in the "Resource Files" section of the OpticStudio Downloads page. After downloading, move to Step 2.
  2. Open the Sentinel Protection Installer installation file you downloaded in Step 1. You will be presented with a welcome screen. 

sentinel protection installer

  1. Click Next and review the license agreement. Select the radio button to accept the terms, and click Next.

sentinel protection installer 2nd

  1. The next screen will ask which setup type you would like to use. To install all program features, select Complete, click Next, and move to Step 5.

    If you want to install only the bare minimum to run the Zemax USB key server without any additional services or drivers, instead select Custom and specify only USB System Driver and Sentinel Keys Server, as per the figure below. 

complete setup     custom setup

  1. You will then see a screen that indicates the installer is ready to proceed. Click Install.

ready to install

  1. If you're running Windows firewall, you will be prompted with an "Important Note" window. You must select YES in order to allow the Windows Firewall to pass traffic from OpticStudio clients to the key server. If you are running any other firewall software, consult its documentation. Ensure that ports 7001 and 7002 open to machines on your LAN.

firewall detected

  1. The installation will then proceed, and you will see the following progress and Installshield Wizard completion screen. Select Finish to complete the installation process. 

install shield wizard     wizard completed

  1. Once installation is complete, plug your network key into a USB port on the keyserver machine. After a few seconds, the key should be detected, and the green LED on the key will illuminate. This indicates that the key is both getting power and that the driver software is correctly configured and recognizes the key. If your key does not light up, see "Troubleshooting license issues with Black USB key licenses" for help. 

After completing the above steps, move to "Viewing key and user info" to verify the license details. 

Viewing key and user info

  1. Open a web browser and navigate to http://localhost:7002. This will open the Sentinel License Monitor page. Note: the localhost address is the "loopback" address and means "use this machine." This address will therefore only work when run from the keyserver. 

sentinel keys license monitor

If the Sentinel License Monitor page does not load, see the Key server troubleshooting section for next steps.

  1. Click Keys Information on the right-hand side of the screen to see more about the key or keys. If the "Keys Information" page loads properly, then the keyserver is working correctly.

    The number under "Hard Limit" should correspond to the number of network licenses you have purchased. "Licenses-In-Use" is the current number of licenses being used, and this should be zero when the server software is first installed. 

sentinel keyserver working correctly

Note: If the "Keys Information" screen is blank or you get a Java error message, see the Keys Information page is blank or has Java error section for more information.

  1. To see more detailed information on what machine and who is using your licenses, select one of the entries under Keys# (usually "1").You must have full administrative privileges on the local machine in order to see this level of detail. If the number is 0, no client machines are using the license and you cannot click it. If you have not set a password on the key server, you will get the following page:

license info

At this point your server setup is done! If you want to create a password on the server, see the next section, Setting a password. To setup Opticstudio client machines, move to Installing and configuring OpticStudio on the client machine.

For more information on advanced settings and features for managing your Black USB network license, see the following resources. 

  • To view and log key usage, see "Monitor and log usage of the Black USB network license."
  • For information on server features, advanced settings and troubleshooting, see the file "README.PDF," located in the following folder on the server: "C:\Program Files (x86)\SafeNet Sentinel\Sentinel Protection Installer\7.6.8\English."

    Note: A Zemax Black USB license is considered a "Sentinel Hardware Key," not a Superpro or UltraPro key. Therefore, be sure to follow the information on the "Sentinel Keys License Monitor," NOT the "Sentinel License Monitor."

Setting a password

If you'd like to prevent end-users from seeing the key information on the keyserver, you must set a password on the keyserver machine. 

  1. On the system where Sentinel Keys Server is installed, run the Password Generation utility (PwdGenUtility.exe) to generate the password. The utility is available at the following path:
  • Windows 32-bit: <OS drive>:\Program Files\Common Files\SafeNet Sentinel\Sentinel Keys Server
  • Windows 64-bit: <OS drive>:\Program Files(x86)\Common Files\SafeNet Sentinel\Sentinel Keys Server.
  1. Type an 8-16 character password that you can remember and click OK. Make note of the password; it will be required when viewing key information. If you forget or otherwise need to clear the password, simply delete the file "sntlpass.dat," which is located in the same folder as "PwdGenUtility.exe."

sentinel password generation utility

  1. Restart the Sentinel Keys Server to make the password change take effect. To do so, open Windows Start and search for "services.msc." Then <right-click> Sentinel Keys Server, and select Restart.

restarting

Keyserver troubleshooting:

The following sections describe common troubleshooting steps for the keyserver machine. 

License Monitor page broken or clients cannot connect

If the License Monitor page is broken or client machines cannot connect, this normally means the Sentinel Keys service is malfunctioning and needs to be refreshed. This can also help if you know there are only a certain number of client machines that are running Opticstudio, but more seats are in use than that. To correct this issue, take the following actions. Note: These apply only on the keyserver machine, as clients do not use the "Sentinel Keys Server" service.

  1. Unplug the USB license if possible. If unplugging is not an option, Step 2 alone will likely resolve the issue. 
  2. Restart the service. To do so, open Windows Start and search for "services.msc." Then <right-click> Sentinel Keys Server, and select Restart.

If the "Sentinel Keys Server" service doesn't exist or will not restart, go back to the beginning of this article and reinstall the Sentinel Protection Server. Follow the above instructions carefully and watch for any error messages. If you are still unable to make it work, contact Zemax Support. Once you have completed reinstallation, verify the "Sentinel Keys Server" is listed in Windows Services. Note: If you have to restart the service more than occasionally, this is typically a sign of a failing USB license. In this case, contact Zemax Support for help. 

restarting

Keys Information page blank or Java error

This section will help if you can open the Sentinel Keys License Monitor home page on the keyserver, but when clicking "Keys information" you receive a blank page or a Java security message. These two outcomes are shown below.

 license monitor     application blocked by java security

To correct this, check the version of the Sentinel Keys License Monitor by opening the admin page at http://localhost:7002.

  • For Version 1.3.6: Make sure "Javascript"  is enabled in the browser's security settings. We recommend Inetrnet explorer 11, Chrome, Firefox or Edge to view the admin page. Older Internet Explorer versions may not work. If you still cannot get the page to work, contact the Zemax Support team. 
  • For Version 1.3.5 or lower: Be aware this version requires the Java Runtime to be installed. The Java browser plugin imay be disabled, misconfigured, or you are using an incompatible browser.Version 1.3.5 requires an Internet Explorer version which supports Java to see this page, or a Firefox version older than 52. Microsoft Edge and Google Chrome no longer support the Java Runtime required to use the Versoin 1.3.5 key server. Switch to a supported web browser and try loading the key info page again. If you still cannot load the page, install the latest "Sentinel Protection installer," available in the "Resource Files" section of the OpticStudio Downloads page, which uses javascript instead.

Configuring the client machine

This section applies if you need to configure your client machine to find a OpticStudio Black USB network license on a keyserver (Key Serial Numbers 22000-40999). This section does not apply to Red USB or a softkey licenses (Key Serials Numbers LXXXXXX). Client configuration for these key types is detailed in "How to configure the keyserver and clients for Zemax network licenses." 

If you already have OpticStudio or Zemax installed on your client machine, proceed to the next section. If not, download OpticStudio from the OpticStudio Downloads page and install it. Detailed instructions are provided in the "Installing OpticStudio for the first time. Note that all versions of OpticStudio as well as legacy Zemax releases as old as version 11 can use a Black USB network license.

Configuring OpticStudio to find the keyserver

Before proceeding with the OpticStudio client configuration, it's a good idea to make sure the client machine can see the network key server. There are a few easy ways to test this. The easiest way is to open a web browser and type the IP address or name of the keyserver machine, followed by the license service's port address of 7002. For example, if the keyserver's IP address is "10.0.1.91," you would type: http://10.0.1.91:7002.You should see the following Sentinel Keys License Manager page:

license monitor

Note: If you do not know the key server's name or IP address, check with the person or group that manages the Zemax key server in your organization. Zemax does not know this information, as we do not host your license key.

If the web page loads successfully, congratulations! The client can reach the keyserver. If you cannot load this web page at all (page not found or similar error), then the keyserver cannot be seen over the network by the client. Stop and resolve this problem before continuing.

Typically, there are firewall settings preventing you from accessing the key server machine or the ports used. Consult the documentation for your firewall software to see how to manually open ports 7001 and 7002. Also, if you are trying to use OpticStudio over a VPN. there may be VPN software or server settings to open the ports. You may need to talk to your IT or network department about this issue, as Zemax is not able to assist in troubleshooting your network. 

Next, you must tell OpticStudio where to find the keyserver machine by editing a configuration file that ships with OpticStudio. This file is called "sntlconfig.xml.bak."

  1. Locate the "sntlconfig.xml.bak" file.
  • For OpticStudio 15 and later, the file is located in the "Documents\Zemax\Configs" folder by default. 
  • For OpticStudio 14 and earlier (including all Zemax versions), the file is located in the OpticStudio (or Zemax) installation location, typically "C:\Program Files\Zemax OpticStudio."
  1. Make a copy of the file "sntlconfig.xml.bak" file. Then rename the file to "sntlconfig.xml." If you cannot see ".BAK" to rename it, then you likely need to configure Windows to display file extensions.
  2. Open "sntlconfig.xml" in a text editor, such as Windows Notepad. You can <right-click> the file, select Open with...Notepad or open Notepad  from the Windows Start menu and drag the "sntlconfig.xml" file into the open Notepad window. The file should look like the following example:

KA-01609_17_sentinel_configuration.png

  1. The line below <ContactServer> needs to be replaced with the IP address or the name of the keyserver machine on your network. In the example, the value to be replaced is "10.0.0.1." If you have multiple keyserver machines, you can specify the order in which to access them by ordering the IP addresses, with the top address is first.
  2. Try launching OpticStudio. If it locates the license server you specified in the above file, it should launch successfully, and you are done! If you receive any errors or are prompted for a code, check the Client Troubleshooting section below.

Client troubleshooting

The following sections describe common troubleshooting steps for the client machine. 

License code prompt

The first time you run OpticStudio, you may be prompted for a license code (shown below). If you see this dialog box, OpticStudio is correctly installed, and the network USB key has been found. You just need a license code to allow OpticStudio to run with your key. To request a license code, refer to "How to request an Opticstudio license code."

prompted to enter license code

Note: being asked for a "license code" is different than being asked for an "activation code." Activation codes are only applicable to Red USB and softkey licenses. 

Error: Cannot Find Zemax Key

If you are able to access the Sentinel Key page through your browser, but you receive a splash screen that does not go away or receive an error reading, "Cannot Find Zemax Key," when you attempt to open OpticStudio, there are a few causes to verify. These are:

  1. All license seats are in use. Have at least one coworker that has Opticstudio running close it and try again. 
  2. Your client machine is not connecting to the keyserver. Re-check the "sntlconfig.xml" file on the client to be sure it has the correct server IP address and port, as described in the "Configuring OpticStudio to find the key server" section.
  3. Your client machine ahs multiple "sntlconfig.xml" files. 
  • For OpticStudio 15 and newer: Make sure there is a "sntlconfig.xml" file ONLY in "\Documents\Zemax\Config;" remove any identically-named files from "C:\Program Files\Zemax Opticstudio."
  • For OpticStudio 14 and earlier: Make sure there is a "sntlconfig.xml" file ONLY in "C:\Program Files\Zemax Opticstudio;" remove any identically-named files from "\Documents\Zemax\Config."

Running OpticStudio on the keyserver

OpticStudio may not automatically use the network license when it is installed on the same server the USB license is attached to. The process to configure it is the same as configuring a client machine, except you have to use either localhost or 127.0.0.1 for the contact server address. 

  1. Locate the "sntlconfig.xml.bak" file.
  • For OpticStudio 15 and later, the file is located in the "Documents\Zemax\Configs" folder by default. 
  • For OpticStudio 14 and earlier (including all Zemax versions), the file is located in the OpticStudio (or Zemax) installation location, typically "C:\Program Files\Zemax OpticStudio."
  1. Make a copy of the file "sntlconfig.xml.bak" file. Then rename the file to "sntlconfig.xml." If you cannot see ".BAK" to rename it, then you likely need to configure Windows to display file extensions.
  2. Open "sntlconfig.xml" in a text editor, such as Windows Notepad. You can <right-click> the file, select Open with...Notepad or open Notepad  from the Windows Start menu and drag the "sntlconfig.xml" file into the open Notepad window.
  3. Under the <ContactServer> section, add "localhost" or "127.0.0.1" to the list, as shown below. 

contact server example

  1. Verify OpticStudio launches successfully, and that's it!

Server and Client Setup Summary

Installing the network version is fairly simple, despite the length of the instructions! Here is a summary of the steps to take. 

  1. Write down the IP address of the machine that will act as the keyserver.
  2. On the keyserver machine, install the Sentinel Protection Installer. Then plug the network key into a spare USB port. After a few seconds Windows will recognize the key, and its green LED will illuminate.
  3. Navigate to http://localhost:7002 in a web browser. Open "Keys Information" to check that the correct number of network licenses are shown.
  4. Move to a client machine, and open "http://{IP address of keyserver}:7002" in a web browser to check that the key can be seen from the client machine. 
  5. Install OpticStudio. Edit the "sntlconfig.xml.bak" file to include the IP address or name of the keyserver. Save the file as "sntlconfig.xml" and verify Opticstudio launches.

Getting Help

If you are having trouble with any of the above steps or cannot get client machines to find a working server, please contact Zemax Support. Please include your Windows Version (7,8,8.1,10), license key number (engraved on your USB license), and any error messages you received. .

KA-01609

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.