Setting Up SSHMenu

Adding the Applet to the Panel

Once you've downloaded and installed the SSHMenu files, you start by right-clicking on the GNOME panel and selecting "Add to Panel":

Select the SSHMenu applet from the list (the icon may not be visible if you've only just installed the files) and add it to your panel.

The first time you add the applet, it will detect that you don't have a config file and will run the setup wizard to create a default config. The wizard attempts to read hostnames from your .ssh/known_hosts file and add them automatically to your menu. This may not be possible if your system is configured to use 'hashed hostnames'. If you've connected to hundreds of servers then the import process may be quite slow and you might not want all those servers on your menu anyway. If you choose to cancel out of the setup wizard, the applet will still be added to your panel — you'll just need to add hosts manually.

If you want to re-run the setup wizard, you should first remove the applet from your panel; then remove the .sshmenu file from your home directory; and then add the applet to the panel again.

Configuring the Menu

You configure SSHMenu by clicking on the applet and selecting 'Preferences' from the menu, to display the preferences dialog:

You can organise your hosts using the 'Up' and 'Down' buttons or by dragging them into the order you want. You can put separators between related groups of hosts and you can add sub-menus and drag hosts into them.

Of course, if you chose not to use the setup wizard then the host list will be empty and before you can organise your hosts you'll need to add some ...

Adding Hosts

You add a host by clicking the 'Add Host' button which will present you with a dialog for entering the Host Connection Details:

When adding a host, the input fields will initially be blank. Fill them in as follows:

Title

This field controls what is displayed in the menu. You might enter the hostname (eg: neptune), a description of the host's role (eg: Web Server), some combination of the two (eg: Web Server (neptune)), or pretty much anything else that makes sense to you.

Hostname (etc)

What you enter in this field will be passed as arguments to the ssh command. The simplest thing is to just enter a hostname:

www.example.com

You can also specify a username:

webmaster@www.example.com

And you can include options before the hostname (see the SSH manual pages for details). For example to connect on a non-standard port number with both agent forwarding and X11 forwarding enabled, you might enter:

-p 8022 -A -X webmaster@www.example.com

You can also enter a command after the hostname. This command will be executed instead of an interactive shell, so when the command completes, the window will close. A common use of this feature is to login to a server and 'tail' a log file:

www.example.com "cd /var/log/apache; tail -f error.log"

The output from the ssh command string can also be piped into a command which will be run locally. This is most useful for session logging:

www.example.com | tee $HOME/ssh_logs/www.log

Finally, (since version 3.14) you can use this field to set environment variables for the terminal program on your local machine (a short list of environment variables will also be propagated to the remote shell, depending on your SSH configuration). For example if your local terminal windows normally use a UTF-8 locale but the server you're connecting to only supports Latin-2 then you might enter something like this to force your local terminal program to use the legacy encoding:

LC_ALL="pl_PL.iso-8859-2" www.example.pl

Warning: If you use the "Open all as tabs" option (described below) one terminal process will be used for all the tabs. If the first host in the menu defines environment settings, those settings will be applied to all hosts and any environment settings defined for later hosts will be ignored.

Geometry

This field is used to specify the position and size of the terminal window. You can safely leave the field blank and your window manager will look after positioning the window for you.

If you do want to specify position and size settings, the easiest way is to use the 'Test' button to launch the terminal, size it and position where you want it and then use the 'Grab' button to get the geometry of the window you launched. This feature uses the xwininfo command to get the geometry details, so if the feature doesn't work, check that you have that utility installed.

Profile

The profile is used to set window colours, fonts and other effects in the terminal window. This drop-down menu lists all the profiles you have set up in Gnome Terminal (i.e.: if the drop-down lists no profiles, you'll need to define them using gnome-terminal, not SSHMenu).

BCVI Forwarding

If you don't know what this option does, you can safely leave it un-ticked and ignore it. For the curious, you can read about bcvi here. If this option is enabled then instead of calling 'ssh', SSHMenu will call bcvi --wrap-ssh --

Use 'OK' to save your host definition; 'Cancel' to exit without saving; or 'Test' to try it out before you save.

SSHMenu Options

Back in the preferences dialog, you can switch to the 'Options' tab:

The options are:

Back up config file on save

When you save your preferences, if this option is enabled, the previous config file ($HOME/.sshmenu) will be copied to a .bak file. In the event that your config got corrupted so the applet wouldn't start, you could rename the .bak file over the main config file.

Enable tear-off menus

If this option is enabled, each sub-menu will have a dotted line at the top. Select this line to 'tear off' the menu and place it somewhere on your desktop. The main menu will not include the tear-off strip — you can always run the standalone menu command sshmenu-gnome.

Include "Open all windows" selection

This option adds a selection to each sub-menu which will open all the host connections on that menu with a single click — each will open in a separate gnome-terminal window.

Include "Open all as tabs" selection

This option adds a selection to each sub-menu which will open all the host connections on that menu with a single click — each will open in a separate tab of a shared gnome-terminal window.