Thoughts on New SSH Feature in Toad 17.0

Toad for Oracle
1

Here are my thoughts on the new built-in SSH feature in Toad 17.0:

  • It really does work once you get the configs correct. That being said...

  • The feature is inadequately documented in the user guide.

  • When using an SSH keys file, TOAD insists on looking for a '.pub' file even when the public key is inside the '.ppk' file, which is what PuttyGen does. Since TOAD can clearly find the correct keys, in either file, and USES them, it seems that it should not need a '.pub' file. I suspect the insistence on a '.pub' file comes before looking in the '.ppk' file to see if there is already a public key present. All you need to do is duplicate the '.ppk' to a '.pub' with the same name, and it will work. (This seems buggy to me.)

  • The Local Port field of the SSH dialog is the port that TOAD connections will use to enter the SSH tunnel. All connections through an SSH tunnel will use a host of 'localhost' and a port of 'SSH Local Port'. The Remote Port field of the SSH dialog is the port of the Oracle Listener (often '1521').

  • When using a TNS Names file, you must create supporting entries in the file BEFORE opening TOAD's connection dialog. (TOAD reads TNS Names each time it opens that dialog.) For SSH, these entries must have a host of 'localhost' and a port of your SSH Local Port (i.e., the local entrance to the SSH tunnel).

  • When using the Direct tab of the Connection dialog, you must specify a Host field of 'localhost' and a Port field of 'SSH Local Port'.

  • When SSH is configured for a connection, the lock icon on the SSH button is closed. Otherwise, it is open. Does this mean 'validly configured' or just 'all the fields filled in'?

  • I like TOAD's ability to import an SSH configuration already defined into a new connection. This is good because setting up the first one was rather troublesome.

  • You must be sure to specify a different SSH Local Port for every different server + Listener port combination you are going to connect to. TNS Names entries must reflect the correct SSH port. If you specify the same port for two target hosts, then the first one connected gets the Local Port. If you then try the second, it will detect the existing tunnel on that Local Port and use it. This should return an 'unknown service' Listener error, but if you have identical service names on multiple servers, then you could find yourself unwittingly connecting to a different database than you expected. (Always have unique service names across all your servers.)

  • If you have multiple Listeners on a server OR a single Listener serving multiple protocols and ports, then you must have a different SSH Local Port for each combination. Since the Listener port is specified in the SSH configuration of a connection, you must have a unique SSH config for each. For example, we use TCP with ANO on port 2521 and TCPS with TLS on 2522, but we have a single Listener for the entire setup. For TOAD connections via SSH, we have to specify two different tunnel configurations, or TOAD will route a connection down the wrong tunnel. We must make sure that the port+protocol combination specified in TNS Names matches the Local Port and protocol of the targeted tunnel and Listener. (If I was not already well familiar with these things, I would have been at a loss to set this up using the information provided in the user guide.)

  • It is not clear what the Test button in the SSH dialog is testing. Is it a TNS Ping through the tunnel, or is it just checking if it can create the tunnel?

  • What happens when the last connection through a tunnel is closed? Does the tunnel stay open for a while or does TOAD close the tunnel immediately?

Cheers,
Russ

2

Hi Russ,

inadequately documented...

Yes. We have been without a full time documentation person for some time now. Management is working on it. Hopefully we'll have one soon. They'll have a lot of catching up to do.

TOAD insists on looking for a '.pub' file

Yes, that's how the 3rd party component that we use works. :man_shrugging:t2:

The Local Port field of the SSH dialog

I'm not sure what you are getting at here. Would you like to see those fields labeled differently?

When using a TNS Names file, you must create supporting entries in the file BEFORE opening TOAD's connection dialog

You can hit F5 to make the login window refresh itself from TNSNames if needed.

When using the Direct tab of the Connection dialog, you must specify a Host field of 'localhost' and a Port field of 'SSH Local Port

Yes. Does that seem wrong or are you just making a comment here?

Does this mean 'validly configured' or just 'all the fields filled in'

If it's in a saved connection, then they must have been at one point validly configured. Otherwise connection would not have been successful and the info not saved. Of course, it could still be wrong sometimes (say, if a password or port changed)

I like TOAD's ability to import an SSH configuration already defined into a new connection.

Thanks. And it's not super-obvious, but you can import settings from PuTTY too. I could possibly add other programs to import from if anyone would like that.

You must be sure to specify a different SSH Local Port for every different server + Listener port combination you are going to connect to.

Good point. I guess that would be true with PuTTY or anything else. I suppose similarly for your point after about listeners.

It is not clear what the Test button in the SSH dialog is testing

Just that it can open the tunnel.

What happens when the last connection through a tunnel is closed?

The tunnel is closed immediately when the last connection using it closes.

3

Hey John,

I am really enjoying the new version and am particularly interested in fleshing out this SSH capability--how it works and what errors mean.

We have been without a full time documentation person for some time now. Management is working on it. Hopefully we'll have one soon. They'll have a lot of catching up to do.

I would like to be able to refer my colleagues to the TOAD user guide section for this, but I will have to make up my own Confluence document for them instead.

The Local Port field of the SSH dialog.

I'm not sure what you are getting at here. Would you like to see those fields labeled differently?

The Local Port is the local entrance to the SSH tunnel. I know this, but I am not sure it would be obvious to everyone. This is the port that TNS Names "port=..." or Direct tab Port field must specify. It is also not obvious that "host=localhost" is also required. Could there be a line like this added to that form: "Use 'host=localhost' and 'port=Local Port' in TNS Names or Direct tab connections." Maybe there could be something on screen that explains how that would be used.

You can hit F5 to make the login window refresh itself from TNSNames if needed.

I did not know this, and it is good to know. I would always close and reopen the dialog to make it reread TNS Names. Thanks for this tidbit.

If it's in a saved connection, then they must have been at one point validly configured....

OK That all makes sense.

but you can import settings from PuTTY too.

I had not noticed the Putty tab on that SSH page. When I click on it, it gives me the full list of my Putty connections. That is great, and I will give it a try. But, in the environment where we would use the SSH feature, we do not have Putty but Tectia.

I guess that would be true with PuTTY or anything else. I suppose similarly for your point after about listeners.

Yeah, this is not an obvious thing when using a tunnel to connect up to a database, and it can be a painful lesson as there are edge cases in which a person could get logged into a database that is totally different from the one they intended and without knowing. It is an unobvious gotcha that can cause grief. This is not an issue with TOAD's SSH feature but for whenever using a tunnel to connect to a database by whatever means. It would be good to point this out in documentation whenever y'all are able to get that done.

Of course, if folks are careful about never duplicating service names across their entire enterprise, then the edge case would never bite them. But, even DBAs are remiss about this using SID instead of service name for a remote connection. For some reason, DBAs who are careful about always directing users to use service names will often, themselves, use SIDs. This can be a gotcha for them in situations in which multiple databases must have the same SID as with Data Guard. The service name is always the better connection target, and SID should be avoided for remote connections.

Cheers,
Russ

4

Hi Russ,

I'll download Tectia and see if I can find/decode their config file where the settings that I'd want to import are stored. If you already have that info and can send your file (maybe with one entry of sample data instead of your actual data), that would be helpful. Hopefully it's in a nice format that's easy to read.

Thanks

5

I am not in our isolated enclave today where we use that. (I could not post here if I was.) Moreover, we cannot get files out of that enclave either. Tectia stores is settings in individual files as a list of key/value pairs (not XML or JSON), but I do not remember where the default location is. I do have my own redirected below My Documents over there, but the default is somewhere below a user's AppData path--I am pretty sure it is the Local/Tectia subdirectory.

Cheers,
Russ