Documentation

Mat M edited this page Dec 7, 2016 · 15 revisions

Introduction to SuperPuTTY

SuperPutty is a Windows application used primarily as a window manager for the PuTTY SSH Client. It allows you to embed PuTTY terminal instances inside of a windows form providing a better tabbed interface when multiple connections are used. Additionally SuperPutty has support for using pscp.exe to transfer files to and from a remote host. Local terminal sessions can be started with MinTTY.

SuperPutty does not do any ssh or terminal management itself since PuTTY does an excellent job of this.

License

Licensed under a liberal MIT/X11 License, which allows this program and source code to be used in both commercial and non-commercial applications. Complete text can be found in the License.txt file included with the download.

System Requirements

  • A PC running Windows (XP, Vista, Windows 7, Windows 8, Windows 10)
  • Running under Linux with Mono and or Wine is not supported due to the Windows proprietary hooks required for the application to run properly
  • The Microsoft .NET Framework 3.5 or newer
  • 32 and 64 bit operating systems are supported
  • The PuTTY SSH Client

Quick Start

Download SuperPutty

Visit the Releases page to download the latest stable version of SuperPutty.

Source code can be downloaded from our Git repository.

More information on the source code and requirements can be found in our Developers document.

Install SuperPutty

SuperPuTTY as of v1.4.0.7 is available with an installer, look for the file named SuperPuttySetup-vx.x.x.x.msi where the x's are replaced by the version number on the downloads page. This is the recommended way to install SuperPuTTY

SuperPuTTY is available as a portable ZIP file, Simply unzip the files to a chosen location on your local disk. It is recommended to store it in a directory which maintains the version number of SuperPuTTY. For example, the directory could be named "C:\SuperPuTTY\SuperPutty-v1.4.0.7".

Depending on the version, the newly extracted files will look something:

License.txt       
SuperPutty.exe         
README.txt        
SuperPutty.exe.config  
WeifenLuo.WinFormsUI.Docking.dll
log4net.dll
ReleaseNotes.txt  
SuperPutty.pdb         
themes

Getting Started

SuperPutty Interface

Menus and Settings

  • File Menu

    • Import Sessions This allows you to import session configuration information from putty, puttyCM, older versions of SuperPutty or files exported by current versions of SuperPutty
    • Export Sessions Export all sessions currently configured to an xml file for archival or for importing to another machine running SuperPutty
    • Open Session Opens a dialog box with a list of your sessions, double clicking on any session will star that session.
    • Switch Session Switch focus to another running sessions, can also be configured as a hot-key for switching under the Tools -> Options menu
    • Edit Sessions in Notepad Launches notepad with the raw xml session date for manual updates.
    • Reload Sessions Reloads the session database
    • Save Layout Saves the current window states and open sessions to the currently running Layout configuration
    • Save Layout As Saves the current window states and open sessions with a new name
  • View Menu

    • Sessions Opens the Sessions List Panel
    • Layouts Opens the Layouts List Panel
    • Log Viewer Opens the Log Viewer
    • Toolbars
      • Quick Connection Show or Hide the Quick Connection Toolbar
      • Send Commands Show or Hide the Send Commands Toolbar
    • Status Bar Show or Hide the Status Bar at the bottom of the window
    • Menu Bar [F3] Show or Hide the Menu Bar
    • Always On Top Forces application to stay in the foreground
    • Fullscreen [F11] Hides all toolbars, panels giving the maximum amount of screen space to any running sessions
  • Tools Menu

    • PuTTY Configuration Opens the putty configuration dialog allowing you to configure putty settings
    • Toggle Command Mask Enables masking characters with a * when input is entered into the Send Commands Toolbar
    • Options [F2] Open the SuperPutty configuration dialog which allows you to configure the behavior of the application
      • General Tab General Settings and external file locations
        • putty.exe location (required): The location on the local disk where putty.exe can be found. Alternatively this could be the location of the kitty ssh application
        • pscp.exe location: The location of the pscp.exe program used to transfer files to and from remote hosts
        • mintty.exe location: The location on the local filesystem of the mintty.exe application
        • Settings Folder (required): The local location you wish to store session and layout databases. Also contains the themes folder for customizing session icons.
        • Default Layout: The layout to load when the application starts which will restore any sessions and tab locations
      • GUI Tab Graphical user interface specific settings are configured here. Holding your mouse over any field will open a tooltip describing the settings purpose.
        • Session Tree
          • Font - Change the default font used in the session tree list
          • Search - Set the session tree search method
            • CaseSensitive Forces searches to be case sensitive
            • CaseInsensitive Forces searches to be non case sensitive
            • Regex Allows using a regular expression when searching for sessions
          • Options:
            • Expand on Startup forces session tree view to be full expanded when SuperPuTTY opens
            • Show Lines between nodes in session list
            • Show Search allows you to make the search box visible or hidden
        • Tabs and Docking
          • Tab Text - Changes how the text on open tabs are displayed
            • Static ??
            • Dynamic ??
            • Mixed ??
          • Switching - Set the method and order for hotkey switching between tabs
            • Visual: Left to Right, Top to Bottom
            • Open: In the order in which the tabs were opened
            • MRU: Most recently used, similar to ALT+TAB in Windows
          • Other:
            • Restrict Content to Document Tabs ??
            • Restrict Floating Windows when checked does not allow tabs to be undocked
            • Ask for Confirmation when closing multiple tabs when checked will confirm you want to close open tabs when exiting the application
        • Session Panel
          • Enable New Session menu ??
        • File Transfer Options
          • Home Directory Prefix is the default path prepended to the username for remote hosts. For example: if your home directory path is "/home/user/jradford", we only know your username, so that allows you to tell SuperPuTTY where to initially load remote files from.
          • Root Directory Prefix is only used when the username is "root", most times it should be simply "/" since root's home directory is generally "/root" on most *nix systems.
        • Misc
          • Opacity sets the opacity of the SuperPuTTY application, The lower the number the more visible background windows will be
          • Minimize to Tray when checked forces SuperPuTTY to minimize to the tray area instead of the Windows Task Bar
          • Show Document Icons ??
          • Case Sensitive Search ??
      • Shortcuts Tab Here you can define shortcut keys to execute specific pre-defined functions in SuperPutty
      • Advanced Tab Control advance application settings
  • Help Menu
    • Documentation Opens the local documentation if installed, otherwise prompts you to load the online documentation (this)
    • Diagnostics Useful tools for developers, Log Window Locations will print the location of any open session windows to the log, Kill stray processes will kill any putty.exe instances running
    • Check for updates Check for a newer version of the SuperPutty application
    • About SuperPutty Brings up a dialog box with information on the SuperPutty application itself

Hotkeys

The SuperPuTTY application allows you to define hotkeys to run a specific predefined task. By Default there are two preset hotkeys:

  • F2 Open SuperPuTTY Options Dialog
  • F11 Switch To/From Fullscreen mode

Other Hotkeys (cannot be changed by user)

  • CTRL+SHIFT+F8 Toggle command mask mode
  • F3 Display or Hide the Menu Bar
  • CTRL+S Save current window layout to the active layout

Additional hotkeys can be configured to do certain tasks and can be found in the Tools->Options->Shortcuts menu option.

Predefined Task List

  • CloseTab closes the tab currently in focus
  • NextTab Causes the next tab to become focused, Order is determined by the order tabs were opened
  • PrevTab Causes the previous tab to become focused
  • Options Open the SuperPuTTY options dialog box
  • FullScreen switch the application to Full Screen Mode
  • OpenSession
  • SwitchSession Bring up the session selector window
  • DuplicateSession
  • GotoCommandBar sets the active control to the Command Bar command input field
  • GotoConnectBar sets the active control to the Connection bar host input field
  • FocusActiveSession resets the focus to the last active session
  • OpenScriptEditor open a dialog allowing you to load/save/edit and send the resulting multiline list of commands to active session windows
  • RenameTab Open a dialog allowing you to rename the active tab

Configuration Files

SuperPuTTY's main settings file is by default located where the USERPROFILE environmental variable is pointed. It is called SuperPuTTY.Settings. You should not directly edit this file but instead use the Tools->Options (F2 Key) to change settings.

If the SuperPutty.settings file does not exist it will be created in the USERPROFILE directory. It can be moved to the Folder where the SuperPutty.exe is located and will be loaded and saved to that location for a more portable solution.

From a Windows Command Prompt (cmd.exe) you can type the following command to view the folder location where the settings are located:

C:\>echo %USERPROFILE%

Will show something similar to this:

C:\Users\jradford

For advanced logging settings and application runtime settings there is a file called SuperPutty.exe.config in the application directory that allows runtime configuration of the SuperPuTTY Application. If you are familier with Log4Net this is where the settings are. This file is for advanced users and in most cases will be left default.

Windows and Toolbars

Sessions Toolwindow

Command Bar

If you need to specify a port for your connection, use the format HOSTNAME:PORT in the Host field.

Layout Toolwindow

Log Viewer

This opens a logging window useful for debugging or error reporting

Command Line Arguments

SuperPutty can be started and controlled from the command line. This allows SuperPutty to be started from other applications. Starting SuperPutty.exe --help from a command prompt will open a dialog showing valid command line arguments

Command Bar

The command bar is used to send commands to open sessions. You can also mask any input in this box by enabling Toggle Command Mask [CTRL+SHIFT+F8] All keystrokes are passed through.

File Transfers

Layouts

Scripting

A scripting language to automate tasks such as logging in is scheduled to be added to a future release.

Script Reference

Script Examples

Known Issues

  • Conflict with TeamViewer's QuickConnect Feature (Issue 309)

    "This issue is being caused by TeamViewer's QuickConnect feature that adds an additional button to every windows toolbar for easy sharing. Adding putty.exe to exception list under the advanced settings solves the problem for me." (phil.pav)

  • Click the Issues tab button on the right for other bug reports from users and developers

External Articles