Tunnelier 3.61 Released
Tunnelier is a friendly and flexible SSH client for Windows which includes state of the art terminal emulation, graphical as well as command-line SFTP support, an FTP-to-SFTP bridge, powerful tunneling features, and also remote administration for WinSSHD. Free for individual use!
Getting Started With Bitvise WinSSHD
If you are a true beginner to SSH, we suggest that you read the following pages as an introduction to the SSH world:
Also, if you plan to use WinSSHD for SSH port forwarding, you should first read our SSH Port Forwarding Guide.
After familiarizing yourself with these general concepts, proceed to one of the following sections of this page to set up your WinSSHD server, depending on your experience and mode of use:
If you run into any problems using WinSSHD, see also our WinSSHD Usage FAQ.
To install WinSSHD, simply execute the distributable that you downloaded from our website and follow the process. As soon as the installer completes, you will have a working WinSSHD installation on your machine: no changes to the default configuration are necessary, you only need to start it.
It is also possible to install WinSSHD in unattended mode, using command-line parameters to the installer. If you wish to make use of this feature, execute the following for a list of supported command-line parameters:
For example, if you wished to install WinSSHD on a fresh machine and start it immediately afterwards, you might execute the following:
WinSSHD-Inst.exe /InstallDir "C:\Program Files\Bitvise WinSSHD" /ActivationCode 01234567890123456789...0123456789
You would use this if you had many WinSSHD installations to make, using an activation code supplied as part of our Simplified Activation Process. To apply a ready-made configuration file as part of the installation process, you would add the '/Settings' parameter and specify the file from which WinSSHD should load its configuration. This file can be created by exporting the WinSSHD settings of an existing installation from its WinSSHD Control Panel.
If you are installing a single WinSSHD installation, you should of course simply execute the installer (without parameters) and follow the instructions provided by the user interface.
Upgrading From a Previous Version
If you have an older version of WinSSHD and wish to upgrade to the latest one, download the new distributable from our website and simply execute it on the machine where your previous WinSSHD version is installed. The installer for the new version will detect the existing installation and will offer to remove it. Accept this option and, after removing the old one, allow the new version to be installed. During this process, your server keypair and settings will be preserved. If you are upgrading from the same major version (3.xx), your existing activation code will also continue to work.
It is also possible to upgrade WinSSHD in unattended mode, without having to have the previous version explicitly removed. This can be done with the following sequence of commands:
net stop WinSSHD
The '/Force' parameter is necessary to force the new version to be installed even though a previous one already exists. You should, however, make sure to install the new version in the same directory where the existing installation resides, otherwise the files of your old version will continue to sit idly on your drive, possibly leading to confusion later on.
Starting WinSSHD and Monitoring Its Activity
The WinSSHD service can be started and stopped in the following ways:
When WinSSHD is running, it logs its activity in the Application section of the Windows Event Log. You can investigate the events logged by WinSSHD either directly through Administrative Tools > Event Viewer, or using the WinSSHD Control Panel by clicking the 'View WinSSHD Log...' button on the first screen.
By default, WinSSHD logs events of all types, errors and warnings as well as informational messages. The logging level can be changed in WinSSHD Settings; however, for security reasons we recommend that you log errors and warnings at least. You should inspect the log periodically to make sure that everything is running as expected.
Note that, if your Application log becomes full, Windows may stop logging new events until the log is cleared or its size restrictions are loosened. You can investigate the maximum size settings of your Application log by selecting it in the Windows Event Viewer and clicking Action > Properties. The log can be cleared either from the Event Viewer or through the WinSSHD Control Panel.
The WinSSHD event log can also be viewed and managed remotely using Tunnelier.
Connecting for the First Time
If you are new to WinSSHD, we highly recommend that you first make sure that you can establish a working SSH connection before you change any settings on the server. If you cannot connect to WinSSHD using its default configuration, this is most likely due to a network or firewall problem that you will need to resolve before you are able to connect.
Before connecting to WinSSHD for the first time, you will need to set up a Windows account with permissions for interactive login, or select an existing one for use with WinSSHD. The selected account needs to have permissions to log on locally; if you cannot use it to log on locally, you will not be able to log in with it through WinSSHD either. Specify the username and password to this account when prompted by the SSH client to log in. To log into a Windows domain account, specify it in the 'domain\account' format.
You can use any SSH client to log into WinSSHD; just make sure that it supports SSH protocol version 2. Some Unix installations still have old SSH implementations which only support SSH version 1; these need to be upgraded, as SSH1 contains security flaws.
Clients that are known to work well with WinSSHD include Tunnelier, CuteFTP Pro, ssh.com's clients and OEMs (F-Secure), VanDyke's clients (SecureCRT, SecureFX), OpenSSH, PuTTY, and others. WinSCP works well in SFTP mode.
Setting Up Public Key Authentication
If your SSH client supports it, you can use public key authentication to log into WinSSHD. (Note that Tunnelier does not support public key authentication at the moment: to log in without being prompted for a password, opt to have the password stored encrypted in the profile. With a sufficiently complex password, security is equivalent to using a public key.)
To set up public key authentication, you first need to generate a keypair on the client, or select one or more existing ones for use with WinSSHD. The procedure for generating the keypair depends on the client software being used. If you are using OpenSSH, keypairs are generated using the ssh-keygen utility. Make sure to generate an SSH2 keypair (not SSH1), using either the RSA or DSA (DSS) algorithm.
Once the keypair has been generated, you need to export the public key into a file that will be uploaded onto the server. The public key file can be either in the standard SSH2 public key format, or in the OpenSSH format. If you are using OpenSSH, the public key file can be exported from an existing keypair again using the ssh-keygen utility (consult 'man ssh-keygen'). Otherwise, the procedure for exporting the public key depends on the client.
Now, transfer the resulting public key file to the machine where WinSSHD is installed, or the machine from which you manage WinSSHD remotely using Tunnelier. Open WinSSHD Settings and go to Access Control > Accounts. If an entry for the user you are configuring is not already present, you need to add one. The name of the entry must match the name of the account that will be used when logging in. Now, click on the 'Keys' column until a button appears. Click that button and a key management window will open. Use the key management window to import the public key.
Configuring WinSSHD Logging
WinSSHD logging is very configurable to allow for a customized logging regime. However, the recommended logging setup for a medium-use server is as follows:
Periodic log file rotation/archival. Depending on the use of the server, the WinSSHD log file may fill with events more or less quickly. If it grows slowly, it may be acceptable to archive the log file once in a while manually, but if it grows quickly, an automatic archival or rotation scheme needs to be implemented.
To implement on-the-fly log file archival, it is important to understand how WinSSHD writes to the log file. WinSSHD will keep the log file open as long as there is activity going on that needs to be logged. If there is no activity in a short while, WinSSHD will close the log file and reopen it when new activity is due for logging. Therefore the log file can be renamed while WinSSHD is still writing to it, and after a while WinSSHD will recreate the log file under the original filename.
Thus, the 'schtasks' or the 'at' utility can be used (or the Add Scheduled Task option in Control Panel > Scheduled Tasks) to periodically launch a simple log cleanup batch file, which could be as simple as this:
The resulting winsshd-YYYY-MM-DD.log files can then be moved out of the way manually or by another automated process running somewhat later than the rename command, allowing WinSSHD time to close and recreate the log file in the meanwhile.
The above example will work fine if the log file is being archived not more than once every day. Here is a more sophisticated example if you want to prepare the log file for archival more frequently:
The for /f exercise is necessary because the output of %time% contains characters not valid in a filename (':'). The result will be filenames of the form winsshd-YYYYMMDD-HHMMSSCC.log.
Using WinSSHD in a Cluster
While WinSSHD does not explicitly implement cluster support, it can nevertheless be easily set up for use in a clustered environment. All you need to do is duplicate WinSSHD settings and keypair on all machines that are part of the cluster. These data are stored in the Settings and Keypair values of the HKLM\Software\Bitvise\WinSSHD registry key, which you can easily transplant from one machine to another using the 'regedit' utility. Make sure only that you install WinSSHD before importing settings into the registry: the WinSSHD registry key should be created by the WinSSHD installer, which takes care to set the key's permissions so as to protect its contents against unauthorized access. If you create the registry key yourself, you should assign proper permissions using 'regedt32'.
Advanced Configuration Using the Wcfg Utility
WinSSHD comes with a textual configuration utility called 'wcfg' which is useful for administering WinSSHD in large-scale installations, where text-based configuration is desired or where very many accounts need to be configured at the same time in a semi-automated fashion. The wcfg utility also allows access to settings which are too new or too complex to have yet been implemented in the graphical WinSSHD Settings utility.
Wcfg also allows remote server administration from client machines where it is not possible to use Tunnelier and its WinSSHD Remote Control Panel feature.
Advanced settings which can be configured through the wcfg utility (but not yet at this time through the graphical interface of WinSSHD Settings) include the following:
Running wcfg. The wcfg utility resides in the WinSSHD installation directory and will normally be run from the Windows command prompt (either locally or remotely in an SSH session). If run without parameters, it will show the options with which it can be used. These can be experimented with freely. This section will focus on interactive use, specifically when wcfg is started with "wcfg import settings -i". This mode allows the user to inspect and manipulate WinSSHD settings dynamically. The interactive session is ended by either committing any changes that have been made (using 'commit'), or by discarding them using 'abort' or 'quit'. Commands such as these are executed in wcfg like in a Windows command prompt.
Command types. In interactive mode, wcfg supports two types of commands for interaction and management of settings:
Note that in non-interactive mode ("wcfg import settings" without the '-i' parameter), wcfg will accept only instructions. Queries are meaningful only in an interactive context.
Getting started. Now would be a good time to look at example usage of the wcfg utility. This example illustrates how wcfg can be used to configure a command to be run automatically whenever a user logs in through WinSSHD. The example also illustrates how special types of queries - ending in '?' or '*' - can be used to learn more about the settings hierarchy, or to get the current settings values of a subset (or the whole) of this hierarchy.
Commands entered by the user in this example are prefixed with "> ". All other text appearing in the example is output by the wcfg utility.
Try executing the following commands yourself to start exploring:
Backslashes in strings. Setting string values through wcfg requires additional attention. Strings use standard C-like escaping to allow representation of non-printable characters and control codes. Like in C, the escape character is the backslash ('\'), and if the backslash itself is desired (i.e. in a Windows path), it needs to be escaped by entering a double-backslash. Example of an escaped string instruction:
access.templates.(name eqi "default").sftpRootDir "C:\\Temp\\SFTP"
This will set the SFTP Root Directory setting for the Default template to C:\Temp\SFTP.
Adding new accounts and templates. Since WinSSHD 3.28, accounts and templates are stored internally in sorted lists. Accounts are sorted according to the value of their 'account' field, and templates are sorted according to their 'name' field. New account and template entries are added in two steps:
This process also applies to all other items which are stored in sorted lists.
Accessing sorted list entries. Sorted list entries such as accounts and templates can be accessed using test expressions:
q access.accounts.(account eq "Domain\\SheilaB").*
This will query the settings for the DOMAIN\SheilaB account. The 'eq' keyword is a string equality operator. The 'eq' operator is case sensitive. However in most cases it is better to use case insensitive string comparison, as follows:
q access.accounts.(account eqi "domain\\sheilab").*
Here the 'eq' has been replaced with 'eqi', which will match regardless of the case.
There are also operators for numeric comparison:
access.accounts.(account eqi "domain\\sheilab").srvSideFwding.s2c.(listenPort == 5554).listenPort 5555
This changes the listening port to 5555 for the first S2C forwarding entry defined for SheilaB's account where the listening port was previously 5554.
A list of operators can be obtained by issuing the simplest query: 'q'.
Removing sorted list entries. Accounts and templates can be removed from their sorted lists as follows:
access.accounts.Erase(account eqi "domain\\sheilab")
This will remove the account settings entry for Domain\SheilaB's account.
Note that if your test expression matches multiple entries, all will be removed.
Help for other list operations can be obtained by querying a sorted list with '?':
If you run into any problems or need any help with the wcfg utility, feel free to write to us on our support forums! Your questions will help us augment this guide so that answers to your questions as well as solutions to any problems will be readily available.
Additional Advanced Modes of Configuration and Usage
COM-based programmatic configuration. WinSSHD comes with a COM DLL which can be used to configure WinSSHD settings programmatically from within a Visual Basic script or any other programming language that provides access to COM objects (.NET for example). Example scripts (renamed to .txt from original .vbs extension):
The WinSSHD configuration COM object can be used for the same purposes as supported by the wcfg utility and the WinSSHD Control Panel - keypair management, import and export of settings, changing and inspection of individual settings values. Write to us for help and an up-to-date reference of the COM object's supported methods.
SFTP plug-ins. WinSSHD supports plug-ins - currently this is limited to the SFTP subsystem, however it can be expanded to WinSSHD itself depending on users' feedback and expressed requirements. For help writing a plug-in, see the example source code that comes bundled with WinSSHD. You will find the .cpp file in the WinSSHD installation directory. If you write a useful WinSSHD plugin, be sure to let us know about it!
Useful Resources and Utilities for WinSSHD Users
Command-Line Utilities. Following is a list of command-line utilities which will likely be useful to WinSSHD users, along with short descriptions and links to documentation and/or source. If there is a utility you feel should be added to this list, let us know - send us an email or post a message on our online support forums.
There are plenty other useful utilities that can be found both already present in Windows or among the Windows Resource Kit Tools.
SSH Tunneling and...
General SSH Information