SSH License Server Access

Normally ATK will locate active license servers automatically, as long as you are on the same network segment and there are no firewalls between your computer and the server. If there are firewalls which can’t be opened for whatever reason, or you wish to access the license server remotely, e.g. from home or while traveling, a very convenient possibility is to set up an SSH tunnel to the license server. To make this work, you need:

  • An SSH client. On Linux you will have this for sure, on Windows you can consider using Cygwin with OpenSSH, PuTTy, or another 3rd party SSH application. Below you will find instructions for different options.

  • The hostname or IP address of the license server - ask your system administrator if you are unsure.

  • An account on a machine which is able to connect to the license server, and to which you can login over SSH. This may be the license server itself, but it can really be any machine which can run ATK using the license server (like a cluster headnode, your office desktop, etc).

Below we will denote

  • the hostname of the license server as LICSERV

  • the machine you SSH into, which can run QuantumATK, as HOST

  • your username on this machine as USER

All these should of course be replaced with the actual hostnames (e.g. server2.uni.edu) or IP number, and username.

Note

Make sure you verify first that HOST can indeed use the license server, else it may be hard to troubleshoot problems further on.

  • Step 1: Open the SSH Tunnel

Linux / Windows with Cygwin Open a terminal window and type

ssh -vvv -N -L 6200:LICSERV:6200 USER@HOST

Lots of information will be printed to the screen - the key messages to look for are highlighted in the redacted screenshot below

../_images/faq_licensing_ssh_tunnel_ssh.png

After you have provided your password, the license tunnel should be open - proceed to step 2.

The process will run in the foreground, it will be waiting for active connections. You will not, however, get a prompt on the remote host (due to the option -N). You need to keep this window open as long as you want the license tunnel to work.

Windows with PuTTY

  1. Download and install PuTTY from here. The easiest option is to choose the Windows installer (putty-0.62-installer.exe, or a newer version if available).

  2. Start PuTTY (if you can’t find a Start Menu entry for it, it’s in C:Program Files (x86)PuTTYPUTTY.EXE).

  3. Under “Host Name”, enter HOST. Replace HOST by the actual IP address or hostname of the computer you have an account on.

    ../_images/faq_licensing_ssh_tunnel_putty1.png
  4. Then, in the Category tree in the left-hand panel, click the + next to SSH to expand the options. Go to Tunnels. - Make sure Local is selected. - Source port: 6200 - Destination: LICSERV:6200 (replace LICSERV by actual license server hostname) - Click Add.

    ../_images/faq_licensing_ssh_tunnel_putty2.png
  5. Do not click Open yet! Instead, go back to the first page (scroll up in the Category tree to find “Session”). Enter a name for the session, for instance “ License Tunnel” and click Save.

    ../_images/faq_licensing_ssh_tunnel_putty3.png
  6. Now click Open to initiate the connection. After you have provided your username and password, the license tunnel should be open - proceed to step 2.

Note

Tip: Under “Connection>Data” you can set your username so you don’t have to type it in each time. Don’t forget to Save the session profile. Next time you want to open the license tunnel:

  • Start PuTTY

  • Select the License Tunnel session and click Load

  • Then click Open

You can also load this profile directly by providing the command line argument -load “License Tunnel” to putty.exe.

  • Step 2: Client License Environment Configuration

  1. Start the QuantumATK license configuration (as described in the Installation Guide); the easiest way is to open a new terminal and type atk_license_config, or on Windows press WinKey+R and type atk_license_config.

  2. Click the Next and OK buttons until you get to the page with license options

    ../_images/faq_licensing_ssh_tunnel_config1.png
  3. Select to use a Floating license, click Next, and on the next page set the server to localhost (the port number will be automatically added, do not enter it):

    ../_images/faq_licensing_ssh_tunnel_config2.png
  4. Complete the configuration utility to save the changes by clicking Next>Next>Finish.

  5. Proceed to step 3 to test the license tunnel.

Note: Once you are able to connect to the license server directly again (say, when you return from your travel), you must rerun this configuration utility to change the configuration back to the original state, which most likely is “Floating” but with the server setting left empty, for autoconfiguration.

If you are familiar with environment variables, you can also just type in the terminal

export QUANTUM_LICENSE_PATH=6200@localhost

In this case the setting only applies to the current session (to this terminal), but it saves you from reconfiguring the license environment when you have direct access to the license server again. You must of course start both “vnl” and “atkpython” from this terminal to have access to the license.

  • Step 3: Testing

To test that the license configuration works, try to run (in a terminal):

atkpython nothing.py

If the license checkout is successful, there will be an error message like

can't open file 'nothing.py': [Errno 2] No such file or directory

That’s ok - the file does indeed not exist, but the point was to check whether QuantumATK manages to find the license or not, and this message only appears if it could.

If the license checkout in unsuccessful, you will instead see a license error message

License Error: (Internal: 719 Feature: ATKPython)
(Err: 9) Feature not found

In this case, first make sure - again - that the HOST computer can run QuantumATK and that there are licenses available, and then try to look for messages in the SSH window; the -vv verbosity option will print lots of debug messages that will be helpful for troubleshooting.

Even in the successful case, you may want to check the SSH messages, especially in case you notice that it takes a rather long time before the message about nothing.py appears. This may indicate that instead of actually using the license tunnel, QuantumATK is using the 2 week built-in trial license. In the truly successful case, you should see a message of the form

debug1: Connection to port 6200 forwarding to multiserver port 6200 requested.
debug1: channel 2: new [direct-tcpip]
debug1: channel 2: free: direct-tcpip: listening port 6200 for multiserver port 6200, connect from ::1 port 50269, nchannels 3

in the SSH window.

Note

  • The license tunnel is only open as long as the SSH process is running. If the network connection times out, or you put the computer to sleep or reboot, you just run the same command again. - It is possible to put the license tunnel into the background by adding the -f option. This saves you from having an extra terminal open for this process, but it’s also harder to restart the tunnel if the network connection is broken, since you must first kill the initial process, since it binds port 6200. Thus we recommend keeping the tunnel running in the foreground unless you are very experienced with SSH tunnels.

  • If you have a HAL (high-availability license) solution with 3 redundant license servers, you need some special considerations. You need to set up a tunnel to the first two HAL servers (the 3rd one cannot be used to check out a license from anyway), on separate local ports (for instance 6200 and 6201), and then set the environment variable manually, in .bashrc (Linux/Cygwin) or via the Control Panel (Windows) as follows:

QUANTUM_LICENSE_PATH=6200@localhost;6201@localhost    (on Windows)
QUANTUM_LICENSE_PATH=6200@localhost:6201@localhost    (on Linux)
SmallBestOriginalRemove