Part 1. WinSSHD Users' Guide

Chapter 1.1

Installing WinSSHD

To install WinSSHD, just 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. However, see also Configuring groups and accounts - this will help you restrict your users' access to those features that they actually need, which will improve security.

Unattended installation

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:

WinSSHD-Inst.exe /?

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
net start WinSSHD

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.

Chapter 1.2

Upgrading from a previous version

Upgrading. If you have an older version of WinSSHD and wish to upgrade to the latest one, download the new distributable from our website and execute it on the machine where your previous WinSSHD version is installed. Starting with WinSSHD 4.10, the installer will detect an existing installation and will automatically remove it before installing the new one. During this process, your server keypair and settings will be preserved.

Upgrading from version 3.xx templates/groups. If you are upgrading from WinSSHD 3.xx and your configuration uses templates/groups, note that version 4 replaces this with Windows groups. These have different semantics. Read Configuring groups and accounts for how group configuration works in WinSSHD 4.

In case you must downgrade. If your WinSSHD settings are highly customized, you should, before upgrading, use the WinSSHD Control Panel to export your WinSSHD settings to a file in case you must later downgrade. Otherwise, during a downgrade, your WinSSHD settings will be reset.

Activation. Any existing activation code you have will work for the new version only if the new version was released prior to the 'upgrade expiry' date embedded in the activation code. If your existing activation code is not valid for the upgraded-to version, the new version will install without a hitch, but will drop into time-limited evaluation. The same will happen when you upgrade from version 3.xx, even if you are still entitled to upgrades, because the activation code format has changed. If your upgrades have expired or will expire shortly, or if you are upgrading from version 3.xx, contact us to get a new activation code. If your original purchase was less than 12 months ago, an upgrade fee will not be required.

If the purchasing process in your organization is slow, we do recommend that you initiate the upgrade extension process several months before your access to upgrades expires!

Unattended upgrade

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
  WinSSHD-Inst.exe /InstallDir 'C:\Program Files\Bitvise WinSSHD'
  net start WinSSHD

You will also need to supply the /AcceptEula parameter to indicate acceptance of the WinSSHD End User License Agreement. Starting with version 4.10, the '/Force' parameter is not necessary any more in order to upgrade; WinSSHD will automatically remove a previous version if it exists. It is also possible to use the installer for unattended installation to a named site. In this case, use the '/Site' parameter instead of '/InstallDir'.

Chapter 1.3

Starting WinSSHD and monitoring activity

The WinSSHD service can be started and stopped in the following ways:

using the WinSSHD Control Panel;
from Administrative Tools > Services;
from the Windows command prompt using commands 'net start WinSSHD' and 'net stop WinSSHD';
the service can also be stopped remotely using the WinSSHD Remote Control Panel in Tunnelier.

Monitoring

In WinSSHD 5, the WinSSHD Control Panel features a Session tab, which shows SSH sessions currently active on the server.

Since WinSSHD 5.06, the WinSSHD Control Panel also features an Activity tab, which shows a history of recent events on the SSH server, such as logins, disconnects, or file transfers. When the WinSSHD Control Panel is open or minimized, it can also be configured to show pop-up notifications for events that show up in the Activity tab.

The Session and Activity tabs are intended to provide a casual overview of SSH server activity, but not a thorough overview. For a thorough overview or diagnostics, consult WinSSHD log files.

Logging

When WinSSHD is running, its default logging behavior in versions 4 and 5 is as follows:

Errors and warnings are logged to the Application section of the Windows Event Log. Many applications write their log messages to this log; to reduce clutter, WinSSHD records no info messages here by default.

You can investigate the Event log either through Administrative Tools > Event Viewer, or using the WinSSHD Control Panel, by clicking the 'View Windows Event Log...' button.

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 Application section of the Windows Event Log can be viewed and managed remotely using Tunnelier.
Errors, warnings and informational messages are logged into managed textual log files, created by default in the Logs subdirectory of the directory where WinSSHD resides. These log files are stamped with the date and time of their creation and can be viewed with any text editing software, e.g. Notepad.

The logging level for each of the two destinations (log files or Windows Event Log) can be changed in WinSSHD Settings. 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. For performance reasons, we recommend not setting the log level higher than info, except temporarily for troubleshooting.

Chapter 1.4

Opening WinSSHD to the internet

WinSSHD is intended to run with minimal configuration after initial installation. However, when installed in a LAN environment, it will not immediately receive connections from the internet by default.

In order to open WinSSHD to the internet, other network components must first be configured. The most prominent such components are the firewall on the machine where WinSSHD is running, and the router on the LAN to which this machine is attached.

Necessary preparation

Before you open WinSSHD to the internet, perform the following important steps:

Follow instructions in Connecting for the first time to make sure you are able to connect to WinSSHD from 'localhost'; that is, that you can connect from a client running on the same machine where WinSSHD is installed.
Follow instructions in Securing WinSSHD to lock down your settings to a degree where you are comfortable with them. After locking down your settings, use a client installed on the same machine to verify that everything is behaving the way you want.

Only when you are satisfied with the security of your settings, and when your settings work when connecting from 'localhost', open WinSSHD to the internet by:

opening the WinSSHD listening port(s) in your firewall, and
configuring your router to forward internet connections to the machine where WinSSHD is installed.

WinSSHD 5.06 and later

Since WinSSHD 5.06, you can configure WinSSHD to perform the above tasks automatically.

Open the section named "Windows Firewall" in WinSSHD Settings. Change the setting for "SSH ports" to "Open port(s) to any computer". This will automatically open your listening ports in your firewall when WinSSHD is running.
Open the section named "Bindings and UPnP" in WinSSHD Settings. Click Edit for the listening port you want to expose. By default, there will be one entry for the publicly known SSH port, 22. Check the setting "Enable UPnP NAT forwarding". This will automatically configure your router to forward internet connections to WinSSHD when WinSSHD is running.

If you have other software or hardware firewalls in addition to the Windows firewall, you will have to configure those firewalls manually.

In order for UPnP NAT forwarding to work, your router must support the Universal Plug and Play standard. Most recent routers do. If yours does not, you will have to configure it manually, too.

WinSSHD 5.05 and earlier

WinSSHD versions prior to 5.06 do not support automatic configuration of the Windows firewall and of routers. For those versions, the Windows firewall and the router have to be configured manually.

Chapter 1.5

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.

In its default configuration, WinSSHD accepts connections on the well-known port number for SSH servers, 22. This is the only port you need to open in your firewall in order to connect to WinSSHD. If you use port forwarding to tunnel other applications through SSH, you should not open any additional ports for the tunneled connections. All tunnelled connections are forwarded through the SSH session, established through port 22.

When connecting to WinSSHD with an SSH client for the first time, log in with the username and password of a Windows account that exists on the server where WinSSHD is running. To log into a Windows domain account, specify it in the 'domain\account' format.

You can use any SSH client to log into WinSSHD, as long as it supports SSH protocol version 2. Some Unix installations and old routers still have archaic SSH implementations which only support SSH version 1. Such installations must be upgraded, as SSH1 contains security flaws. In general, security software, in particular such as an SSH server, should always be kept up-to-date to minimize exposure to security flaws.

Clients that are known to work well with WinSSHD include Tunnelier (which works best), as well as CuteFTP Pro, ssh.com's clients, F-Secure / WRQ / Reflection, VanDyke (SecureCRT, SecureFX), OpenSSH, PuTTY, FileZilla, and many others. WinSCP works well in SFTP mode.

Chapter 1.6

Configuring groups and accounts in WinSSHD

Immediately after initial installation, when started using the original default settings, WinSSHD will accept password, NTLM or Kerberos-based login to any Windows account that has Windows permissions to establish an interactive logon (or in the case of NTLM and Kerberos, a network logon) on the machine where WinSSHD is running.

When a Windows account user logs in, WinSSHD will impersonate the security context of that Windows account throughout the user's SSH session. With the default, initial-installation settings, WinSSHD will allow any successfully logged on user to take any action (running a program, accessing a file, connecting to another machine) that the user is permitted by Windows operating system and file system permissions.

Most administrators will find it desirable to configure WinSSHD in a way that restricts users from accessing parts of the server which Windows permissions do not normally prevent them accessing. The groups and accounts sections of WinSSHD Settings provide the means for this configurability. The groups and accounts in WinSSHD Settings are an additional layer of security settings which are imposed by WinSSHD on top of the Windows permission system; not replacing it, but providing complementary settings which Windows does not on its own provide.

Additionally, virtual groups and virtual account settings provide the means to differentiate users in WinSSHD without having to create separate Windows groups, or having to create and maintain a Windows account for every user.

Windows groups and accounts

By default, the WinSSHD configuration for Windows groups and accounts is very simple and consists of a single 'Everyone' group. In a default configuration, the WinSSHD settings for the Everyone group apply to all Windows accounts that log in through WinSSHD.

When a user tries to log into WinSSHD with a Windows account, WinSSHD determines the settings for that account in the following manner:

Account settings. The entries in 'Windows accounts' are searched to find a match for the account for which login is being attempted. If a match is found, the settings in the account entry are superimposed on the settings found for the account's group (below), and if the 'Specify group' option is enabled, it is used to choose the account's group settings entry, as well.
Group settings. If a match was found for an account settings entry; and if the entry specifies a Windows group to be used for this account (the 'Specify group' setting is enabled); and if there is a corresponding WinSSHD group settings entry for that group; and if the Windows account is actually a member of that group; then WinSSHD will use that group settings entry.

Otherwise, WinSSHD looks up the local and domain groups of which the candidate account is a member:
- If none of those groups have a corresponding WinSSHD group settings entry, the Everyone group settings entry will be used.
- If only one of those groups has a corresponding WinSSHD group settings entry, that one group settings entry will be used.
- If more than one of those groups have a corresponding WinSSHD group settings entry, then, if this is a domain account configured in Active Directory, and if the Active Directory settings for the account specify a primary group which has a WinSSHD group settings entry, that group settings entry will be used. Otherwise, that one of the group settings entries which has the lowest numeric priority value will be used.

This means that:

WinSSHD account settings can be configured individually by adding individual account entries in 'Windows accounts'.
WinSSHD account settings can be configured en masse, without having to add or maintain individual account entries, by configuring WinSSHD settings for a number of Windows groups. When there is no individual account settings entry, WinSSHD will use appropriate group settings according to the algorithm described above.

When configuring settings for multiple Windows accounts through groups, automatic expansion of environment variables in string configuration fields may be helpful. WinSSHD will substitute environment variables in string fields such as 'Terminal shell', 'Initial directory' and 'SFTP root directory'. For Windows accounts, at least the following environment variables will be defined: , , (the name of the group settings entry selected, or 'EVERYONE'), and (defined if the value of references a domain group).

Virtual groups and accounts

For administrators who want to avoid setting up a separate Windows account for every SSH user, WinSSHD provides the means to create virtual accounts. Virtual accounts behave exactly as Windows accounts, except for the following differences:

Scope.

Windows accounts. A Windows account is created in Windows, and can be used to log into WinSSHD whether or not there is a corresponding WinSSHD Windows account entry. A Windows account exists outside of WinSSHD as a Windows security principal.

Virtual accounts. A virtual account is created by adding an entry to 'Virtual accounts' in WinSSHD Settings. A virtual account exists only inside WinSSHD, but there is no awareness of virtual accounts in applications that an SSH session launches. Instead, those external applications are aware of a Windows account that is configured to back the virtual account, providing an operating system-level impersionation context.
Groups.

Windows groups. The mapping between Windows account settings entries and Windows group settings entries in WinSSHD can be complex. It depends on the Windows account's actual Windows group memberships, Active Directory primary group settings, the 'Specify group' setting in the WinSSHD account settings entry, etc.

Virtual groups.The mapping between a virtual account and its corresponding virtual group is straightforward. The virtual account entry always directly specifies a single corresponding virtual group.
Password.

Windows accounts. The password of a Windows account is maintained by Windows. It is possible to change it either using the Windows Control Panel or Computer Management, or through WinSSHD during SSH user authentication, or using the included bvPwd command line utility.

Virtual accounts. The password of a virtual account is maintained in WinSSHD Settings. It is configured by the administrator and cannot be changed by the user of the virtual account.
Backing Windows account. A virtual account still requires configuring a backing Windows account to provide the operating system-level impersonation context. WinSSHD will impersonate this backing Windows account when the virtual account is logged into. A single backing account can be used for any number of virtual users, and the backing account can be defined either for individual virtual accounts or for whole virtual groups. However, because WinSSHD needs to log into the backing Windows account when accepting a virtual account logon, the password for the backing Windows account needs to be stored in the WinSSHD password cache. It will not be possible to log into a virtual account until a password cache entry for the backing Windows account is configured. The password cache entry can be set either manually using the WinSSHD Control Panel, as well as through wcfg (using 'wcfg pass set'), or programmatically using the WinsshdCfgManip COM object.

WinSSHD 5.02 and higher allow you to avoid explicitly configuring a backing Windows account for virtual users. When installed on machines that are not domain controllers, WinSSHD creates and manages a local Windows account. This account is used if no 'Windows account name' is configured for a virtual user. The Windows account is named 'WinSSHD_VirtualUsers' on default (unnamed) WinSSHD installations, but can be named differently if you installed WinSSHD as a named site. Run 'net user' from a Command Prompt to discover the name of this account. Domain controllers do not have local accounts, so this feature is not available on domain controllers.

In all other respects, a virtual account is just like a Windows account. Virtual account settings are superimposed on the corresponding virtual group settings just like it happens with Windows group and account settings entries. All the WinSSHD settings for virtual accounts that look the same as for Windows accounts behave the same way.

Chapter 1.7

Using WinSSHD in a domain

WinSSHD fully supports domain environments. However, WinSSHD does implement its own authentication layer on top of Windows authentication. In order to properly implement authentication, WinSSHD needs to be able to query information about domain groups and users.

If the WinSSHD log file reports errors which indicate that authentication is failing because WinSSHD is unable to obtain information from the domain, perform the following steps to make sure that WinSSHD can read domain user and group information:

On the Domain Controller, open 'Active Directory Users and Groups' under Administrative Tools.
In the View menu, enable 'Advanced Features'.
Right click on the Users container in the tree view, and click Properties.
In the Security tab of the new dialog, click Advanced.
In the Permissions tab of the new dialog, add the computer running WinSSHD with ApplyTo=ThisObjectAndAllChildObjects and ReadAllProperties=Allow.

Domain Order

Unless configured differently, WinSSHD will require all SSH clients to fully qualify a username if logging into a domain account. This means that a username of 'John' will work only for a local account named 'John'; if you wish to log into a domain account named 'Domain\John', the domain needs to specified in full.

To avoid the need to fully qualify domain usernames, add your domains to the Domain Order list in WinSSHD Settings. When an SSH client attempts to log in with a username that is not fully qualified, WinSSHD will then automatically search for the username in the configured domains, in the configured order. This ensures that non-qualified usernames will be resolved deterministically, which would not be guaranteed without this setting.

Chapter 1.8

Network vs. interactive logon

Windows recognizes different types of logon with subtly different security implications. WinSSHD can be configured, on a per-account or per-group basis, to use either of the following two logon types:

Interactive logon. By default, this logon type is configured in WinSSHD Settings for all Windows group entries. This logon type is therefore used, by default, for all Windows accounts - except those logging in with GSSAPI (Kerberos or NTLM) authentication.

Use of the 'interactive' logon type requires a Windows account to be granted the right to 'Log on locally' in the Windows Security Policy at the server. This is not usually a problem, since by default all users are granted this logon type - except on domain controllers. On domain controllers, the right to 'log on locally' is granted by default only to administrators. To enable regular Windows accounts to log in with this logon type on a domain controller, the right to 'log on locally' must be granted to the relevant groups or accounts in Domain Controller Security Policy, found in Administrative Tools.
Network logon. By default, this logon type is configured in WinSSHD Settings for all virtual group entries. This logon type is therefore used, by default, for all virtual accounts. This logon type is also used when a Windows user authenticates with GSSAPI (Kerberos or NTLM) - a limitation imposed by Windows.
Use of the 'network' logon type allows the user to log in via WinSSHD even if the underlying Windows account is not granted the right to 'Log on locally' in the Windows Security Policy at the server. However, on Windows 2003 servers, the default filesystem permissions normally block access to cmd.exe and other command line tools when a logon session does not have the 'interactive' logon type. On such servers, the terminal shell can only be accessed with this logon type if the default filesystem permissions for cmd.exe and other command line tools are modified.

Selecting the right logon type

We recommend that users who require terminal shell access use the 'interactive' logon type. It will usually also make sense for them to log into WinSSHD as Windows users, not as virtual accounts.

On the other hand, we recommend that users who will use only file transfer and/or tunneling use the 'network' logon type. If this use is outside of a domain environment, it may also make sense (less overhead) to create for these users virtual accounts internal to WinSSHD instead of creating for each user a separate account in Windows.

Chapter 1.9

Setting up public key authentication

If your SSH client supports it, you can use public key authentication to log into WinSSHD. Our own recommended SSH client, Tunnelier, has strong support for public key authentication, as well as other authentication methods.

To set up public key authentication, you first need to generate a keypair on the client, or select one or more existing keypairs for use with WinSSHD. The procedure for generating the keypair depends on the client software being used:

If you are using Tunnelier, click the link titled 'User keypair manager' in the Login tab. You can generate, edit, import and export keypairs in the dialog box that pops up.
If you are using a different client, you need to follow its process for generating keypairs. For example, in OpenSSH, keypairs are generated using the ssh-keygen utility. Make sure to generate an SSH2 keypair (not SSH1). Use either the RSA or the 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. The exporting and importing process depends on the client being used:

With Tunnelier, use Tunnelier's User Keypair Manager to export the public key in either format.
If you are using a different client, you need to follow its process for exporting the public key into either the standard SSH2 format or the OpenSSH public key format. If you are using OpenSSH, the public key file can be exported from an existing keypair using the ssh-keygen utility (consult 'man ssh-keygen').

Once your public key file has been exported, transfer it to the machine where WinSSHD is installed, or the machine from which you manage WinSSHD remotely using Tunnelier. If you are exporting the public key from Tunnelier and you are also using Tunnelier to administer WinSSHD remotely, no transfer is necessary - use the WinSSHD Remote Control Panel. Open WinSSHD Settings and go to Access Control > Windows Accounts - or, if you are setting up public key authentication for a virtual account, Virtual Accounts. If an entry for the user you are configuring is not already present, add it. Now, click on the 'Keys' link and a key management window will open. Use the key management window to import the public key.

Chapter 1.10

Fine-grained tunneling restrictions

'Tunneling' or 'port forwarding' refers to the ability of an SSH client (a) to have WinSSHD initiate a TCP/IP connection to another server on the SSH client's behalf (called client-to-server tunneling), or (b) to have WinSSHD accept incoming TCP/IP connections on a server's interface and port and forward those connections to the client (called server-to-client port forwarding). (You can learn more in our Short guide to SSH port forwarding.)

If your requirements are simple, WinSSHD provides two easy ways to control a user's or group's access to tunneling. In the WinSSHD settings entry for the account or group, there are fields Permit C2S port forwarding and Permit S2C port forwarding. Disable the first and the user will not be able to tell WinSSHD to initiate outbound connections. Disable the second and the user will not be able to instruct WinSSHD to listen for connections to forward to the SSH client.

Sometimes, however, such simple controls are not sufficient. For example, you may want to allow the user to use port forwarding to access a service provided by a particular machine on the server's local network; but you don't want to allow the user to use this capability to access any server on the internet, e.g. as a proxy for web browsing.

Such fine-grained control is provided by the Connect rules and Listening rules settings available in each group or account settings entry. This section will attempt to explain how these settings work, with two examples following at the end.

Connect rules

Connect rules control what destinations the SSH client will be able to connect to using client-2-server port forwarding. There are two types of connect rules: 'IP rules' and 'DNS name rules'. IP rules control permitted destinations based on their IP address, and DNS name rules control them based on their DNS name.

An IP rule allows you to specify either a complete IP address (significant bits = 32) or a whole subnet (significant bits = 8 for 255.0.0.0, 16 for 255.255.0.0 or 24 for 255.255.255.0). The IP address 0.0.0.0 with significant bits = 0 will match any destination.

A DNS name rule allows you to specify a destination either using a specific DNS name or a wildcard of the form *.com, *.bitvise.com or *.research.bitvise.com. A lone wildcard (just *) will match any destination.

IP rules and DNS name rules are automatically sorted by WinSSHD in order of decreasing specificity: the most specific rules are processed first and the more general ones later. The most specific rule match takes precedence.

Connect rules are always processed IP rules first, DNS name rules second. If a match is found in IP rules, the DNS name rules are not searched. This means that if there's a blanket 0.0.0.0 rule in IP rules, the DNS names will never be searched because the blanket IP rule will match all destinations.

If WinSSHD gets a client-to-server tunneling request for which there is no match in the account's Connect rules, or if there are no Connect rules or no account settings entry in the first place, the Connect rules of the account's group settings entry will be processed. If no match is found in the group Connect rules either, the connection is rejected.

By default, the Connect rule list for a group contains a single entry allowing access to all destinations if 'Permit C2S port forwarding' for the user is true. An account's Connect rule list is empty by default, passing all decisions to Connect rules defined for the user's group.

Listen rules

Listen rules control what server interfaces and ports the user will be able to bind in order to accept connections and forward them to the SSH client. Since interfaces are always specified by their IP, there is need for only one rule list.

A listen rule identifies an IP of one of the server's network interfaces and a port range for which the SSH client is allowed or denied listening. The special IP 0.0.0.0 matches any interface.

A listen rule may contain additional Accept rules which control the origin hosts from which connections to the interface and port range defined in the listen rule will be accepted. By default, the accept rule list contains a single entry allowing connections from all sources.

If WinSSHD gets a server-to-client tunneling request for which there is no match in the account's Listen rules, or if there are no Listen rules or no account settings entry in the first place, the Listen rules of the account's group settings entry will be processed. If no match is found in the group Listen rules either, the tunneling attempt is rejected.

By default, the Listen rule list for a group contains a single entry allowing all interfaces and ports to be bound if 'Permit S2C port forwarding' for the user is true. An account's Listen rule list is empty by default, passing all decisions to Listen rules defined for the user's group.

Example 1: Permit a client-to-server destination

Suppose your WinSSHD resides on machine 10.10.10.5 in your internal network, and you wish to allow the user to connect through WinSSHD to a Remote Desktop service running on machine 10.10.10.16. You would first need to decide whether to configure this policy for the user's group or for the individual user. If for the individual user, you would need to add a WinSSHD account settings entry for the user if one does not yet exist. Then, you would open the group or account settings entry that you wish to configure this restriction for, and perform the following:

Add 'allow' rule for client-2-server connections:
1. open the 'Connect rules: IP rules' list and click Add
2. under IP rule, input the IP address of the server to which the user is allowed to connect - in our example, 10.10.10.16
3. under Significant bits, enter 32 to specify that the IP address in this case identifies an individual IP (10.10.10.16), not a subnet (e.g. 24 for 10.10.10.x)
4. under Port range rule, set 'Port from' to the RDP port (3389), and 'Port to' to the same value
5. under Instructions, enable the 'Allow connect' setting and leave the rest at defaults
6. click OK to confirm and add the configured rule
Add 'deny' rule for client-2-server connections:
1. click Add in 'Connect rules: IP rules'
2. the default will be a rule that denies all connections. Just click OK to add the rule.

In this example, if you wanted to prohibit the user from setting up any kind of server-to-client forwardings whatsoever, you would simply set 'Permit S2C port forwarding' to false. Otherwise, if you wanted to configure a specific range of ports and interfaces where the SSH client may instruct WinSSHD to listen, you would add appropriate Listen rules as in the Example 2 (below).

Example 2: Permit a server-to-client binding

Suppose your WinSSHD server machine has two network interfaces: 10.10.10.5 is the private IP address in the local area network and 123.23.12.111 is the server's public IP address on the internet. You know that the user who will be logging into WinSSHD will need to run a program on the server side which will initiate a TCP connection to the client, and the user will achieve this using server-to-client port forwarding. You want to allow the user to forward connections from the server's local network through the server's 10.10.10.5 private network interface, as well as from the server itself using the 127.0.0.1 loopback interface, but you do not wish to allow the user to listen for connections from the internet through interface 123.23.12.111. You also want to restrict the user to listening on ports 1024-65535.

Again, you would first need to decide whether to configure this policy for the user's group or for the individual user. If for the individual user, you would need to add a WinSSHD account settings entry for the user if one does not yet exist. Then, you would open the group or account settings entry that you wish to configure this restriction for, and perform the following:

Add 'allow' listening rule for 10.10.10.5:
1. open 'Listening rules' list and click Add
2. under IP rule, input the IP address of the interface - in our example, 10.10.10.5
3. under Port range rule, enter 1024 into 'Port from' and 65535 into 'Port to'
4. enable the 'Allow listening' checkbox
5. under Instructions, enable the 'Allow connect' setting and leave the rest at default values
6. click OK to confirm and add the configured rule
Add 'allow' listening rule for 127.0.0.1:
1. repeat steps under 1, but using 127.0.0.1 instead of 10.10.10.5. You should now have 2 listening rules.
Add 'deny' rule for other listening interfaces:
1. click Add in 'Listening rules'
2. the default will be a rule that denies binding on all listening interfaces and all ports. Just click OK to add the rule.

In this example, if you wanted to prohibit the user from setting up any kind of client-to-server forwardings whatsoever, you would simply set 'Permit C2S port forwarding' to false. Otherwise, if you wanted to configure a specific range of destination servers and their ports to which the SSH client may connect, you would add appropriate Connect rules as in Example 1 (above).

Chapter 1.11

Using WinSSHD in a cluster

While WinSSHD does not explicitly implement cluster support, it is designed to be cluster-friendly, and can be straightforwardly 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. In WinSSHD 5.xx, these data are stored in the Config subdirectory of the WinSSHD installation directory, and you can easily copy them between machines. Make sure only that you install WinSSHD before copying files in this directory: the WinSSHD installation directory should be created by the WinSSHD installer, which takes care to set filesystem permissions so as to protect its contents against unauthorized access.

Password Cache

If your WinSSHD setup uses either of the following:

Virtual accounts that have an explicitly configured backing account in Windows (not the default account managed by WinSSHD); or
Windows accounts that use public key authentication;

then WinSSHD will rely on a password cache to store the passwords for the Windows accounts in question. If such configurations are used in a cluster situation, then the WinSSHD password cache needs to be copied from the primary to the secondary installation as well.

The password cache consists of encoded values stored under the following registry keys:

32-bit Windows: HKLM\Software\Bitvise\WinSSHD
64-bit Windows: HKLM\Software\Wow6432Node\Bitvise\WinSSHD

Chapter 1.12

Scriptable configuration with wcfg

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. Wcfg also allows remote server administration from client machines where it is not possible to use Tunnelier and its WinSSHD Remote Control Panel feature.

Note: Everything that can be configured through wcfg can also be configured through the graphical WinSSHD Settings utility, and vice versa. Users who don't need scriptable configuration do not need to learn wcfg. Such users should simply use the graphical WinSSHD Settings utility, which is launched by clicking Edit Settings in the WinSSHD Control Panel.

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. This section will focus on interactive use, specifically when wcfg is started with 'wcfg settings importText -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:

Queries: queries are used to inspect the current value of a setting or a hierarchy of settings, and they are always prefixed with 'q '. The 'q' prefix makes it clear to wcfg that you desire to inspect a certain value or set of values, not to change them. Example query:
q access.winGroups.*
This query displays settings configured in the Access Control > Templates section of the WinSSHD Settings utility.
Instructions: instructions look similar to queries, however the absence of a 'q ' prefix tells wcfg that you desire to change the value of a particular setting, and there is a suffix specifying the desired value of the setting. Example instruction:
access.winGroups.(group eqi 'Domain Users').permitSftp false
This instruction turns off SFTP access for the Windows group named 'Domain Users'.

Note that in non-interactive mode ('wcfg import settings' without the '-i' parameter), wcfg will accept only instructions. Queries are interpreted 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:

  q
  q ?
  q *
  q %
  q server.?
  q server.*
  q access.?
  q access.*
  q access.winGroups.?
  q access.winGroups.*
  q access.winGroups.New.?
  q access.winGroups.New.*
  q access.winAccounts.?
  q access.winAccounts.*
  q access.winAccounts.New.?
  q access.winAccounts.New.*

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.winGroups.(group eqi 'Domain Users').sftpRootDir 'C:\\Temp\\SFTP'

This will set the SFTP Root Directory setting for the 'Domain Users' group to C:\Temp\SFTP.

Adding new accounts and groups. Accounts and groups are stored internally in sorted lists. Some of the fields in each list entry are the entry's sort key; when you do a query ending in '.?', these fields are displayed with a '>' prefix. Other fields in each list entry may have a unique constraint placed on them; such fields will be marked with a '!' prefix in the results of a query ending in '.?'. For example, Windows accounts are sorted according to the value of their 'winDomain' and 'winAccount' fields. On the other hand, Windows groups are sorted according to their 'priority' field, and the values of the 'groupType', 'winDomain' and 'group' fields must be unique.

New account and group entries are added in two steps:

First, the entry is initialized with the new settings it will contain. In this step, it is referred to with the keyword 'New', for example:
  access.winAccounts.New.winDomain 'Domain'
  access.winAccounts.New.winAccount 'SheilaB'
  access.winAccounts.New.loginAllowed true
  access.winAccounts.New.sftpRootDir 'c:\\SftpRootDirs\\SheilaB'
  ...
Then, when the initial data for the new list entry is configured, it is committed into the list:
access.winAccounts.NewCommit

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 groups can be accessed using test expressions:

q access.winAccounts.(winAccount eq '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.winAccounts.(winAccount eqi 'sheilab').*

Here the 'eq' has been replaced with 'eqi', which will match regardless of the case.

There are also operators for numeric comparison:

access.winAccounts.(winAccount eqi '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 valid in test expressions 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.winAccounts.Erase(winAccount eqi 'sheilab')

This will remove the account settings entry for Domain\SheilaB's account. However, if your test expression matches multiple entries, all of them will be removed. If this is a problem, query the sorted list for the ID of the entry in advance:

q access.winAccounts.%

From this output (which is similar to but more concise than .*), we may learn that Domain\SheilaB's account entry is number 31. Therefore, we might remove this specific entry as follows:

access.winAccounts.Erase 31

Help for other list operations can be obtained by querying a sorted list with '?':

q access.winAccounts.?

If you run into any problems or need any help with the wcfg utility, feel free to post to our discussion groups. 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.

Chapter 1.13

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). 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.

A list of the COM object's supported methods can be found in the WinSSHD installation directory in the file WinsshdCfgManip.idl.

Virtual filesystem providers. WinSSHD 5.xx supports pluggable filesystem providers. Third parties can implement custom providers to support any type of backing store for files accessed with SFTP or SCP via an SSH session. Possibilities include SFTP/SCP access to files contained in an encrypted database; or a bridge that permits SFTP/SCP access to files actually hosted on an FTP server. Third-party providers can be mounted concurrently with WinSSHD's default provider, FlowSfsWin.dll, allowing SSH users to access the Windows filesystem and a third-party provider's virtual filesystem concurrently.

Virtual filesystem providers need to be implemented as C++ DLLs, compiled with Microsoft Visual Studio 2005. No licensing or royalty fees are required. Feel free to contact us to receive the libraries and header files needed.

Chapter 1.14

Useful resources and utilities

Command-line utilities. The 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.

bvRun. Included with WinSSHD. Executes a process in a custom manner. In particular, allows an SSH user to run a process so that it will not be terminated when the SSH session terminates using the -brj parameter. (This requires the 'allow job breakaway' feature to be enabled in WinSSHD settings.) Execute 'bvRun /?' from your WinSSHD directory for help.
bvPwd. Included with WinSSHD. Allows a user to change their Windows password from a Command Prompt, in case they are using an SSH client that does not support password change. Execute 'bvPwd /?' from your WinSSHD directory for help.
wstat. Included with WinSSHD. Displays SSH sessions currently connected to WinSSHD, as well as their tunnelled TCP/IP connections. Also included is C++ source code which demonstrates obtaining this information programmatically. Execute 'wstat' from your WinSSHD directory for help.
NetStat. Included with Windows. Run 'netstat -ano' for a list of active TCP/IP connections and listening ports, including PIDs of the processes using them. Valuable in diagnosing networking issues.
SchTasks and At. Included with Windows. These commands allow Cron-like scheduling of tasks from the Windows command line. SchTasks is more capable and is a replacement for At in Windows XP. Documentation can be found online at Microsoft's site in the Windows XP Command-Line Reference A-Z.

There are plenty other useful utilities that can be found both already present in Windows or among the Windows Resource Kit Tools.

Resources:

Microsoft's Command-Line Reference A-Z documents the command-line utilities available in the latest versions of Windows.
The Command-Line Reference A-Z also links to instructions for writing Windows batch files (command line shell scripts executed by Cmd.exe), a useful skill for any Windows server administrator - particularly when managing machines remotely via SSH and SFTP.
Very useful is Rick Lively's comprehensive Commands reference, which contains detailed information about the majority of Windows command-line utilities, and in particular their availability in different versions of Windows.

Part 2. Tutorials

Chapter 2.1

Frequently Asked Questions about Using WinSSHD

If you have a problem using WinSSHD - and even if you don't - you should first become comfortable with the WinSSHD log files. WinSSHD writes warnings and errors into the Application section of the Windows Event Log, but it also writes more detailed information to textual log files. These are located by default in the 'Logs' subdirectory of the WinSSHD installation directory.

Whenever you have a problem, the WinSSHD log files are the first place you should look.

Personal Edition
Getting It Up and Running
File Transfer Issues
Public Key Authentication
Account Settings
Usage
Contacting Support

Personal Edition

Q00. Where do I get an activation code for personal use?

No activation code is needed to use WinSSHD for personal use. If your WinSSHD Control Panel is saying that there is an evaluation period, this means that you installed WinSSHD as the Standard Edition. In this case, you need to uninstall WinSSHD, re-install it again, and choose the Personal Edition this time.

Note, however, that WinSSHD may be installed in the Personal Edition only by genuine, non-commercial personal users who are not using WinSSHD as part of a commercial endeavor, and are not using it in an organization, whether commercial or otherwise. All commercial or organizational use requires a purchased license.

Q01. How do I use WinSSHD Personal Edition on a domain controller?

The WinSSHD Personal Edition does not support domain accounts, and will not work on a domain controller. If you chose the Personal Edition during installation, you need to uninstall WinSSHD and then re-install it, this time selecting the Standard Edition. The Standard Edition requires a purchased license, and is not available free of charge for personal use.

Getting It Up and Running

Q10. After I install WinSSHD, what do I need to configure before I can start using it?

For a basic open setup, just start the WinSSHD service and it will work. Use one of your existing Windows account names and passwords to log on. For a basic usage case, where you want to use WinSSHD for remote administration, the default WinSSHD settings do not need to be changed. However, after you have established a successful connection, consider locking down your settings to prevent SSH access to Windows accounts and features that you do not want to be accessible over SSH.

Q11. How do I log in to a Windows domain account?

Specify the username in the standard domain, backslash, account format - for example, 'company\john' - or with a fully qualified name, for example 'john@company.com'. Alternately, add the domain name to the Domain Order setting.

Q11B. How do I log in to a Windows domain account without having to specify a fully qualified username?

The 'Domain order' setting in WinSSHD Settings is provided for this purpose. Configure an entry specifying the domain name where you would like WinSSHD to start looking up unqualified usernames. You can configure multiple such domain names.

Q12. What client software can I use to connect to WinSSHD?

You can use any client program that supports SSH, as long as it implements SSH version 2 - the newer and secure version of the protocol. There are multiple types of SSH clients, including terminal session clients, file transfer clients, port forwarding clients, command execution clients, and they come in all sorts of combinations. If your client machine runs Windows, you can use our Tunnelier client for most purposes. Tunnelier offers an excellent terminal console, graphical file transfer, dynamic and manual port forwarding, as well as scriptable command-line clients and an FTP-to-SFTP bridge. Also available for Windows is PuTTY, which includes SSH file transfer programs 'pscp' and 'psftp'. On Unix platforms, the OpenSSH package is freely available and provides the 'ssh' program for terminal sessions and port forwarding, as well as 'scp' and 'sftp' for file transfers.

Q13. My WinSSHD log shows an error like 'Failed to bind listening socket', and I cannot connect to WinSSHD.

Such an error indicates that another application is already listening on the port you have configured for WinSSHD. The default port is 22, and this port is used as default by all SSH servers. It is likely that you already have another SSH server running on your machine, and that it is occupying port 22. You either need to shutdown the other SSH server, or configure WinSSHD to listen on a different port.

Q14. I can only log in with an administrator account - attempting to log in with a regular account fails.

There are two most common causes.

You are trying to log in with an account configured in WinSSHD to use the 'interactive' logon type, but this account does not have the Windows permission to log on locally. On domain controllers, this permission is not granted to regular users by default and must be enabled in the Domain Controller Security Policy.
You have successfully logged in with an account configured in WinSSHD to use the 'network' logon type, or you logged in using GSSAPI (Kerberos or NTLM) authentication, but starting the terminal shell failed with an Access Denied error. This is because default filesystem permissions on Windows 2003 servers grant access to cmd.exe and other command line tools only to 'interactive' users. Switch this user or group in WinSSHD to use the 'interactive' logon type, or modify filesystem permissions for cmd.exe and other command-line tools to allow execution by users logged in with the 'network' logon type.

For more information, please read the Network vs. interactive logon section in the WinSSHD Users' Guide.

Q15. I'm trying to get some SSH client to work with WinSSHD. However, the session gets terminated immediately after connecting, and the WinSSHD event log tells me: 'Unable to create child process: Access is denied.' What is going on?

In order to provide SFTP, SCP, terminal shell, or exec request functionality, WinSSHD must have permission from Windows to execute a child process in the name of the user. You have probably configured your machine in such a way that, when the user logs in and WinSSHD starts impersonating that user, WinSSHD loses permission to execute the necessary child processes. In order to use WinSSHD, you must configure your machine so that the remote user will be able to run executables in the WinSSHD installation directory; plus, of course, whatever programs you want the user to be able to execute, such as the terminal shell - 'cmd.exe'. Read and execute access is also required to the dynamic load libraries that programs use - in particular, system libraries which reside in the \Windows and \Windows\System32 directories.

File Transfer Issues

Q21. When users log in, they can see all drives on my server. How do I limit them to a certain directory?

This feature is configurable either per-account or per-group in WinSSHD Settings. When editing account or group settings, click 'Virtual filesystem layout' in the configuration tree on the left side of the account or group settings window. If configuring settings for a specific user, as opposed to a group, disable the 'Use default layout' checkbox. Edit Mount Points, and change the 'Real root path' setting for the default mount point (virtual mount path '/') to the directory you want the user to be able to access. The user or users will now be able to see only files and subdirectories in that folder.

If you want the user to be able to access multiple directories in independent locations, add additional mount points.

Public Key Authentication

Q30. Someone wants to use public key authentication to log into the WinSSHD server that I am administering. They have already sent me their public key file. How do I tell WinSSHD to use the public key file when that user logs in?

Open WinSSHD Settings and go to Access Control > Windows accounts (or Virtual accounts if this is a virtual user). If an entry for this user is not already present, you need to add one. For Windows accounts, the name of the entry must match the Windows username that will be used when logging in. Now, click Edit to open the account entry in a new window, and click the 'Public keys' link. A key management window will open which you can use to import the public key.

If you are using one of the later WinSSHD 3.xx versions, the name of the link is '0 Keys' or 'n Keys'.

If using WinSSHD 4 or newer, please also read this page in the WinSSHD Users' Guide for important information about how WinSSHD account and group settings work.

Q31. I am unable to import a user's public key within the WinSSHD user key management window. I keep getting a dialog box telling me that the public key could not be imported. What could be the problem?

It is most likely that the public key you are trying to import is not in the right format. It might be an SSH1 public key file instead of an SSH2 key, or it might be something entirely alien. The formats supported by WinSSHD are the standard SSH2 public key format, and the OpenSSH SSH2 public key format. The OpenSSH SSH1 public key format is different and incompatible with SSH2.

Q32. I set up my account for public key authentication, but the next time I tried to log in, I still got asked for a password. Why?

When you enable public key authentication for an account and configure a public key, WinSSHD needs to cache the password so that later you can log in with just the public key. There are two ways for WinSSHD to get the password: either you enter it yourself in WinSSHD Control Panel > Manage password cache, or using the wcfg utility; or WinSSHD gets it from the SSH client. If there's no password in the cache on your first login attempt after you set up public key authentication, WinSSHD will ask you for a password - even if your client already authenticated successfully using a public key. If you supply a valid password, WinSSHD will cache it, and subsequently, or until it changes, you will not be asked to enter it again.

Q33. How do I set up public key authentication with Tunnelier?

Generate a keypair in Tunnelier's User Keypair Manager. Use the Export button to export the public key in standard SSH2 format. Transfer the resulting file onto the WinSSHD machine. Follow the instructions in Q30 (above) to import the public key into WinSSHD. In Tunnelier, configure the Login : Authentication : Initial Method setting so that Tunnelier will use your generated user keypair for authentication. You can also save your Tunnelier settings into a profile for convenience. You will now be able to connect with public key authentication.

Account Settings

Q40. How do WinSSHD account settings work?

Please read this page in the WinSSHD Users' Guide for this important explanation.

Q43. How can I limit a user so that they cannot access files outside of a certain directory?

The answer depends on what sort of access you have in mind. For shell access and remote execution, jailing a user is possible only through Windows file system permissions. On the other hand, if you are permitting the user only file transfer access (using SFTP and SCP), you can configure a limited-access virtual filesystem for the user by editing settings for their account or group in WinSSHD Settings. If editing account settings, disable 'Use default SFS map', then open SFS virtual filesystem mount points, and set the 'Real root path' setting for the default mount point ('/') to the directory you want them to access.

Usage

Q51. How can a user change their password remotely?

WinSSHD supports changing a Windows account password during SSH user authentication by using a client that supports this feature, such as Tunnelier.

Additionally, WinSSHD comes with a 'bvPwd' utility which allows any user to change their password if they know what it currently is. The utility can be found in the WinSSHD installation directory; run it with 'bvPwd -h' for help. Additionally, administrators can use the 'net user' command intrinsic to Windows to change any user's password - type 'net help user' in a Command Prompt for help.

Passwords for WinSSHD virtual accounts cannot be changed by the virtual user themselves, but can be changed by an administrator in WinSSHD Settings or using wcfg.

Contacting Support

Q. I read the entire FAQ, but it didn't help me solve my problem. What do I do?

Visit our discussion groups. Use the search function to see if your issue has been raised in the past. If not, feel free to post a support query in the appropriate forum, in which you describe your problem in as detailed manner as possible. The more information you supply, the greater the chance of a swift and effective resolution.

Chapter 2.2

Using WinSSHD as SFTP, SCP file server

WinSSHD is a capable SSH server which provides multiple ways of secure remote access to Windows. However, a very frequent usage scenario is to configure WinSSHD strictly as a file server, without exposing the machine to terminal shell, tunneling and other types of access. This tutorial explains step-by-step how to configure WinSSHD for a primary role as an SFTP and SCP file server.

Install WinSSHD. Do not start it yet.
Click Edit settings. If you have already performed any changes to the settings here, select the root 'Settings' page, click 'Load defaults', enable 'Reset settings to defaults in all descendant pages in the hierarchy', and click OK. This will bring you back to the initial default configuration.
Go to Access control > Windows groups. You should see a single group of type 'everyone'. Edit the settings for this group. Disable the Login allowed setting. Click OK. This will prevent direct login into WinSSHD with Windows usernames and passwords.
Go to Access control > Virtual groups. There should be a single group called 'Virtual Users'. Edit the settings for this group.
1. Leave the Windows account domain and Windows account name empty. WinSSHD needs a Windows account to provide a security context for the SSH session. Leaving these settings empty instructs WinSSHD to use a local account that is created and managed by WinSSHD automatically. (This requires WinSSHD 5.02 or newer.)
2. Disable the following settings:
  - Permit terminal shell. This prevents your users from accessing the command interpreter.
  - Permit exec requests. This prevents your users from executing arbitrary programs via SSH.
  - Permit C2S port forwarding. This prevents your users from accessing other network services through WinSSHD.
  - Permit S2C port forwarding. This prevents your users to provide access to their own network services through WinSSHD.
3. Change also the default virtual filesystem mount point: set it to a harmless, empty directory. This protects against failure to configure a proper virtual mount point for a particular user. You can change the default mount point by clicking 'Mount points' under 'Virtual filesystem layout' in the page tree on the left, then clicking Edit and setting 'Real root path' to an innocuous directory.
Now, go to Access control > Virtual accounts and set up as many accounts as you like. For each account, you only need to set the following settings:
- Virtual account name. This is the name that your user will use to log in.
- Virtual account password. This is the password that your user will use to log in (unless you set up public key authentication).
- Virtual group. Unless you create additional groups, or rename the existing one, you only have one option here: the default group, 'Virtual Users'.
- Use default layout (under 'Virtual filesystem layout'). Turn this off to configure a virtual filesystem mount point for the user.
- Mount points under 'Virtual filesystem layout'. Set the default mount point to a directory to which you want to restrict the user. Make sure that the backing Windows account has the desired read or write permissions to this directory.
  
  You will probably not want to use the default setting here (Real root path set to empty): it provides access to all parts of the filesystem accessible with the backing Windows account's permissions. This is good for remote administration, but unsuitable for a more restricted setup as a file server.

Having configured WinSSHD in this way, it will only accept connections from users who know one of the Virtual account usernames and passwords you have defined. WinSSHD will allow these users to only use SFTP or SCP, and none of the other SSH protocol features, and will restrict their file access to each user's virtual mount point folders.

To guarantee that your users can access the directories you configured for them, make sure that the Windows account WinSSHD_VirtualUsers has Windows filesystem permissions to access those directories. The WinSSHD_VirtualUsers account is not created until WinSSHD has been started at least once, and may be named differently if you installed WinSSHD as a named site. Run "net user" from a Command Prompt to discover the name of this Windows account.

If you installed WinSSHD on a domain controller, the above steps will not be sufficient. Domain controllers do not have local accounts, so WinSSHD cannot manage a local account to provide the security context for virtual users. In this case, consult Configuring groups and accounts in WinSSHD to learn more about how WinSSHD operates, so that you can configure it properly.

Chapter 2.3

Securing Your WinSSHD Settings

At default settings, your WinSSHD installation will permit any user who knows a valid Windows username and password to log in through WinSSHD and use the following SSH services:

SFTP and SCP file transfer, allowing the user to access all files and folders that can be accessed by the Windows account they used to log in.
Access to a Command Prompt via terminal console, allowing the user to execute all programs that can be executed by the Windows account they used to log in.
Routing TCP connections through WinSSHD, either from the client to the internet, or from the internet and to the client.

Securing WinSSHD involves:

Identifying which of the above features you want to limit or disable, and doing so.
Configuring WinSSHD to allow access only to a restricted subset of Windows accounts configured on the system, or only to virtual accounts configured in WinSSHD itself.
Making sure that strong authentication is in use for those accounts that can log in.

In order to avoid frustration, do not start locking down WinSSHD settings prematurely. Make sure that you can establish a connection first. Make sure that you and your users can use the WinSSHD features that you want to use.

To avoid security issues, you can conduct such testing and preliminary setup with a closed firewall. Install an SSH client such as Tunnelier on the same machine where WinSSHD is installed, and use that client to connect to WinSSHD to test the connection. After you are satisfied that the features you require work correctly, start securing WinSSHD settings. Once your settings are locked down to provide only the types of access you require, open the SSH port in your firewall and permit outside connections.

Disabling features you don't want

If you intend to use WinSSHD for file transfer, you will want to disable the other SSH features that you don't want your clients to use. The easiest way to disable features for all users is to do so at the group level.

At this point, you may want to consult Configuring groups and accounts in WinSSHD for an overview of how WinSSHD treats Windows- and virtual accounts and groups.

In the most common and straightforward case, you will have a single Windows group for 'everyone' in WinSSHD settings. This Windows group controls WinSSHD settings defaults for all Windows accounts that might log in through WinSSHD.

Open this group and disable the following settings:

Permit terminal shell. This prevents your users from accessing the command interpreter.
Permit exec requests. This prevents your users from executing arbitrary programs via SSH.
Permit C2S port forwarding. This prevents your users from accessing other network services through WinSSHD.
Permit S2C port forwarding. This prevents your users to provide access to their own network services through WinSSHD.

If you are using WinSSHD for more than only file transfer, you may want to leave some of these features enabled. In particular, if you are using WinSSHD for tunneling, do not disable port forwarding. If you are using WinSSHD for remote program execution, do not disable exec requests. If you are using it for the terminal console, do not disable the terminal shell. Or disable these settings for the 'Everyone' group, but enable them for the particular users that need these features.

If you will be using virtual accounts, apply the same restrictions to your virtual groups. (By default, there is a single virtual group named 'Virtual Users'.)

Restricting access to chosen accounts

The first step in this process is to go to the 'Everyone' group under Windows groups in WinSSHD Settings, and disable the 'Login allowed' checkbox. This prohibits SSH login to everyone except the users you configure.

In order to allow a Windows account to log in, you now need to merely add a WinSSHD Settings account entry under Windows accounts, and configure the following fields:

Windows account domain. Leave this empty if you're adding a local Windows account.
Windows account name. The name of the Windows account you are adding. It must be an existing account already created in Windows.
Login allowed. Set this to 'Yes'. This permits this particular user to log into WinSSHD, overriding the fact that login is disabled in group settings.

For virtual users, similarly, all you need to do is add a virtual account entry, defining a username and password. For virtual users, you don't need to disable the group default for 'Login allowed', because there are no virtual users other than those that you configure, in the first place.

Limiting directory access

By default, WinSSHD permits each user to access any and all parts of the filesystem that Windows filesystem permissions allow them access to. Frequently, you want to limit users to be able to access only a particular directory. Note, however, that it is only secure to impose such restrictions if you have also followed instructions above and disabled access to port forwarding, exec requests, and the terminal shell.

Filesystem access is controlled under the Virtual filesystem layout section of per-account and per-group WinSSHD Settings. To have a safe default, open 'Virtual filesystem layout' for the Everyone group, edit the default mount point ('/'), and set the Real root path to point to an innocuous, empty directory. Or, if all your users should have access to the same folder, you can configure this to point to that directory.

In per-account settings, you can configure a different set of mount points for each user. Under 'Virtual filesystem layout' settings for the user, disable the Use default layout checkbox. Then configure the 'Real root path' for the default mount point ('/') to specify the directory which you want this user to access.

You can configure multiple mount points in this way, permitting the user to access a selected number of server directories. You can also use the Read-only mount checkbox to allow the user to only read, but not write to, files in a particular directory.

Ensuring strong authentication

Password authentication can be secure, but only if the passwords are complex. Unless you want the general public to log into a particular account, you need to ensure that all accounts for which you are permitting SSH login - be they Windows accounts or virtual - are configured with complex passwords. WinSSHD does impose delays and IP blocking to prevent aspiring attackers from successfully guessing a password, but this will not help if your passwords are as simple as '1234' or 'password1'.

A reasonably complex password would consist of at least 15 random characters from an alphabet of a-z, A-Z, and 0-9. If the chosen password is truly random, this provides the equivalent of about 90 bits of security. This is not as good as a 128-bit symmetric key, but is secure if the only way the attacker can guess a password is by trying to log into WinSSHD.

If you also want to protect against an attacker who has access to a cryptographic digest of your password, such as by having a copy of your authentication database, or by having physical read access to your system drive, then you need at least 22 characters from the same alphabet (a-z, A-Z, and 0-9) for security equivalent to a 128-bit symmetric key.

Expanding the password alphabet to include non-alphanumeric symbols may not be as great an idea as commonly supposed. Even if 28 symbols are included, the number of characters needed for 128-bit security is still 20. The 10% savings in password length are outweighed by the hassle of entering the symbols, and even more so by problems with programs that interpret such symbols incorrectly.

It is crucial, however, that you do not create your passwords by hand. If you do so, they will not be random. Use a password management utility to securely store your passwords in an encrypted database, and to randomly generate passwords of the desired length.

Alternately, you can configure your SSH client and WinSSHD to use public-key authentication. For more information, consult the public key section of the WinSSHD Usage FAQ.

Chapter 2.4

A short guide to SSH port forwarding

SSH port forwarding, or TCP/IP connection tunneling, is a process whereby a TCP/IP connection that would otherwise be insecure is tunneled through a secure SSH link, thus protecting the tunneled connection from network attacks. Port forwarding can be used to establish a form of a virtual private network (VPN).

To illustrate how port forwarding works, let us use an example. Suppose you are the network administrator in a company that has two buildings. In Building #1, there are numerous workstations residing in the subnet 10.1.1.*. In Building #2, there are multiple servers residing in the subnet 10.2.2.*. The two buildings are separated by a busy street with parking spaces on each side, and the subnets in the two buildings are linked wirelessly through an antenna on the roof of each building. The workstations in Building #1 are running a legacy client application that uses an unencrypted TCP/IP session to communicate sensitive data with the servers in Building #2.

One day, someone in your company notices that an unmarked black van has remained parked on the street between the two buildings for several days. As your CEO realizes that sensitive data is being transmitted unencrypted between the two buildings, he becomes worried that the van parked outside might be collecting the company's confidential information. He orders you to solve the problem ASAP.

What you do is this:

On each of the client workstations in Building #1 (in the above example, workstation 10.1.1.7 is shown), you install an SSH client. On the machine in Building #2 that runs the server for your legacy application, you install an SSH server. You configure the SSH client with the following client-to-server port forwarding rule: for each connection that comes on interface 127.0.0.1 and port 999, forward that connection to the SSH server, and request the SSH server to forward that connection to host 127.0.0.1 (relative to the server), port 123.

Now, your application client doesn't connect to the server directly anymore. Rather, it connects to the SSH client, which encrypts all data before transmission. The SSH client forwards the encrypted data to the SSH server, which decrypts it and forwards it to your application server. Data sent by the server application is similarly encrypted by the SSH server and forwarded back to the client.

Previously, the data that was being radioed between the two buildings was sent in plaintext and could be captured by anyone parking on the street below. Now, the data is encrypted using the SSH protocol, and is virtually impossible to decipher. The next day after installing SSH, you observe that the black unmarked van is gone.

Now, let us comment on the above example. It corresponds with the following C2S (client-to-server) port forwarding rule in the SSH client:

Listen interface: 127.0.0.1 (this ensures that only connections from the local client machine, or loopback connections, are accepted for forwarding)
Listen port: 999
Destination host: 127.0.0.1 (important: the target address is relative to the server, not the client, so 127.0.0.1 will work fine if the target application server is listening on all interfaces - 0.0.0.0)
Destination port: 123

Note that the listening interface configured on the SSH client is 127.0.0.1. By configuring the listening interface, you tell the SSH client what kinds of connections it will accept. If you configure the listening interface to 127.0.0.1, the SSH client will only accept connections originating on the same machine. If you configure the listening interface to equal the IP address of one of the network cards on the machine, the SSH client will accept only those connections that arrive through that network card. If you configure the listening address to 0.0.0.0, the SSH client will accept connections regardless of their origin.

Next, you will note that the listening port has been set to 999. The listening port could be set to any figure between 1 and 65535 that is not already occupied by another application listening for connections on the same machine. In this case, the SSH client listening port has been set to 999, but it could just as well have been set to 123, the same port at which the application server is listening.

Now comes the most confusing part: the address of the destination host. It is important to understand that, in a client-to-server port forwarding rule, the target host address is relative to the SSH server, not the client. This is the address that the SSH server will connect to when a connection needs to be forwarded. In this case, the target host address is set to 127.0.0.1 to have the SSH server connect to the application server which is running on the same machine.

Finally, the destination port specifies the port on which the target TCP/IP server is listening - in this case, 123.

The port forwarding configuration shown in the above example is strict: it minimizes the exposure of unencrypted data by constraining the SSH client to reside on the same machine as the application client, and the SSH server to reside on the same machine as the application server.

On the other hand, if you are only concerned about eavesdropping between the SSH client and the server, and do not mind unencrypted data in the local subnets, you might configure your SSH port forwarding rules like this:

This corresponds with the following C2S (client-to-server) port forwarding rule in the SSH client:

Listen interface: 0.0.0.0 (this opens up the SSH client's forwarding socket to connections from other machines)
Listen port: 123
Destination host: 10.2.2.9 (the target application server is not on the same machine as the SSH server, so we need to enter its address as visible from the SSH server)
Destination port: 123

With this setup, you only need one SSH client to forward the connections of multiple application clients; since the SSH client's listening address is configured to 0.0.0.0, the application clients do not need to reside on the same machine. With appropriately configured port forwarding rules, you can use the same SSH session to forward connections to multiple application servers, which can reside on machines different from the SSH server.

Even though our examples above only discuss client-to-server port forwarding rules, the concept of server-to-client port forwarding is entirely symmetric. Only the roles are reversed: with S2C forwarding, the listening address is relative to the SSH server, and the destination host address is relative to the SSH client.

It is a common mistake to define both a C2S as well as an S2C rule for the same forwarded connection. This is not necessary and will not work. S2C rules are required only if you are forwarding other connections which are established in the direction from the server to the client. Such connections are normally independent from, and unrelated to, those established from client to server. Only one type of rule is necessary for each connection.

Chapter 2.5

Single-Click Remote Desktop Forwarding

Since Tunnelier 3.28 and later, this section is now largely obsolete. A Remote Desktop session can be launched by simply clicking on a button when the SSH session is established, and Tunnelier will setup all the settings and launch the Remote Desktop client for you.

Consult the below instructions if for some reason the automatic single-click solution fails, or if you must configure Remote Desktop to be tunnelled manually.

Securing Remote Desktop With SSH

Remote Desktop, previously known as Terminal Services, is a feature in Microsoft Windows that allows a user to interact with a Windows machine's desktop remotely from another Windows machine. The server machine must be Windows Vista Business or Ultimate, Windows XP Professional, or Windows NT/2000/2003/2008 Server. The client machine can be any version of Windows equipped with Remote Desktop Connection, or the Terminal Services client (mstsc.exe).

Although Remote Desktop takes measures to protect against passive attacks, it does not appear to provide much protection against an active attack. Also, opening port 3389 on the server means another Windows service open to remote vulnerability probing. Both issues can be avoided by routing the Remote Desktop session through SSH port forwarding. On the server machine, an SSH server such as WinSSHD must be installed. On the client machine, an SSH client, such as Tunnelier, must be configured so that connections to a specific local port will be forwarded to port 3389 on the Remote Desktop server. One must then direct the Remote Desktop client to connect to the SSH client instead of directly to the server, and the connection will be forwarded over the SSH-secured link.

Note that one must always be diligent in verifying the SSH server's fingerprint when establishing the SSH connection for the first time, otherwise SSH won't be better at defending against active attacks either.

Listening Port on XP vs. Win2K and Earlier

On Windows 2000 and earlier, the Terminal Services client does not support connecting to a custom listening port. For this reason, with the older Terminal Services clients, 3389 must be used as the port on which the SSH client will be listening. If this is not possible because a Terminal Services server is running on the same machine, a newer Remote Desktop client can be downloaded from Microsoft which supports connections to non-default ports.

On Windows XP, a port other than 3389 can be entered in the 'Computer' field of the initial RDC dialog box - for example, 'localhost:3390'. This is useful if you need to setup the SSH client to listen on a port other than 3389, for instance if port 3389 is already occupied by the local Remote Desktop server.

Connecting to Localhost on XP prior to SP2

Prior to Windows XP Service Pack 2, the Remote Desktop client on Windows XP explicitly prevented the user from connecting to localhost. For users who have not yet upgraded to SP2, there is a way around this limitation. Have the SSH client listen on 127.0.0.2, and connect the Remote Desktop client to 127.0.0.2 instead of localhost.

With the Windows XP SP2 version of the Remote Desktop client, it is possible to connect to localhost (127.0.0.1) as long as the port being used is other than the default (3389). Note however that connections through 127.0.0.2 do not work any more on Windows XP SP2. Because the 127.0.0.2 address is necessary prior to Windows XP SP2, the same forwarding setup will not work on SP2 as well as pre-SP2 machines.

Step-by-step instructions

Follow these steps if you wish to get quickly up and started with Remote Desktop over SSH. It is advised that you try to understand what is being done by each one of the steps presented. The difference between understanding and not understanding is frequently the difference between a security measure which works and one that only appears to.

Install WinSSHD on the server (the machine you wish to access with Remote Desktop).
No changes to the default WinSSHD configuration are required to use Remote Desktop over SSH. You may wish to make changes to the default WinSSHD configuration later on, to restrict what WinSSHD features are accessible to remote users. However, for the time being, keep your WinSSHD settings at default until your Remote Desktop over SSH is up and running.
Apart from installing WinSSHD, the only thing you need to do on the server is ensure that there is a Windows account which you can use to log on locally. This will normally be a Windows account which already exists and which you plan to be using to log into with Remote Desktop.
Start the WinSSHD service from the WinSSHD Control Panel.
Install Tunnelier on the client (the machine from which you wish to be accessing the server machine).
Configure the following settings on the Login tab in Tunnelier. Click also the 'Help' link on the Login tab for help with any of these settings.
1. Host: The IP address or DNS name of the server that you are accessing.
2. Port: You will normally use the default value, 22. This must match the port that WinSSHD is listening on. If you have made no changes to the default WinSSHD configuration to change the port it is listening on, use 22.
3. Username: The Windows account name with which to log into the server. This must be a valid Windows account name with local logon permissions on the side of the server.
4. Password: The password with which to log into the server, belonging to the account name specified by Username.
5. Store encrypted password in profile: You may optionally wish to enable this setting so that you will not be asked to reenter the password each time when logging in after Tunnelier has been restarted.
In the C2S Forwarding tab in Tunnelier, add a new entry and configure the following settings for this entry. Click also the 'Help' link on the C2S Forwarding tab for help with any of these settings.
1. Status: This will be 'enabled' by default, leave it that way.
2. Listen interface: The default value is 127.0.0.1. If the client machine is running Windows XP prior to Service Pack 2, change this to 127.0.0.2. If you are running Windows XP SP2, or if you are running Windows 2000 or earlier, leave this at the default value.
3. List. Port: This is the local (client-side) port on which Tunnelier will be listening for a connection from your Remote Desktop client. Set this to 3389 if running Windows 2000 or earlier. Otherwise, if using Windows XP, set this to 3390 or an arbitrary port number. The chosen port number needs to be reflected in your instructions to the Remote Desktop client (below). You can also execute 'netstat -an' from a command prompt and examine the output to ensure that your chosen port is not yet occupied. It is fine if there is not already a line like '0.0.0.0:(yourPortNr) ... LISTENING'.
4. Destination Host: specifying localhost will work, assuming the Remote Desktop server is listening on all interfaces, which is normally the case. If it is listening on a particular interface, you can determine the interface by executing 'netstat -an' on the server and examining the output for a line like 'xxxxxx:3389 ... LISTENING'. If xxxxxx is 0.0.0.0, the Remote Desktop server is listening on all interfaces and 'localhost' will work here. Otherwise, the xxxxxx is the IP address that you need to enter in this field. Using 'localhost' will normally work though.
5. Dest. Port: 3389.
Click the Login button in Tunnelier and observe the log area for any errors. If the session is established without errors, the SSH setup is running, now you just need to connect through it with the Remote Desktop client.
Run the Remote Desktop client. In Windows XP, you can find it through Start : All Programs : Accessories : Communications : Remote Desktop Connection. Alternately you can run it from a Windows command prompt (execute 'mstsc') or through Start : Run : 'mstsc'.
In the Computer field, enter 127.0.0.1 if you configured the 'List. Port' setting in your C2S rule as 3389 (on Windows 2000 or earlier). On Windows XP prior to SP2, enter 127.0.0.2:xxxx, where xxxx is the port number you chose for the 'List. Port' field in your C2S rule. On Windows XP SP2 or higher, enter 127.0.0.1:xxxx, where xxxx is that same port number.
Click Connect. The SSH session in Tunnelier needs to be established with the C2S port forwarding rule active when you do this. If all is well, you should have a secure Remote Desktop connection to the server machine shortly.
You can make sure that your Remote Desktop connection is going through Tunnelier by checking the Tunnelier log area for a message saying 'Accepted client-to-server connection from ... to localhost:3389' corresponding to each connection attempt you make. Likewise, when your Remote Desktop session closes, Tunnelier should output a log message stating 'Closing client-to-server forwarding channel from ... to localhost:3389'.

Troubleshooting

If you encounter problems establishing the SSH session, you will receive diagnostic information in the Tunnelier log area, as well as in the log entries recorded by WinSSHD on the server side. Especially in the case of an authentication failure, the WinSSHD log entries will contain important diagnostic information. Inspect the WinSSHD log entries using the Windows Event Viewer on the server side.

Please see our contact and support page for more information and links to documents about how to go about resolving problems with Tunnelier and WinSSHD.

Chapter 2.6

Securing Windows File Sharing With SSH

Tunneling Windows file shares is useful if you want to comfortably access files on a Windows machine that is only accessible via SSH, and you don't want to use SFTP or SCP.

To tunnel Windows file shares over an SSH connection, you need to forward connections on port 139 on the sharing-consumer machine via SSH to the sharing-provider machine. The exact setup differs depending on the version of Windows on the sharing-consumer machine:

Windows 2000: configure the SSH client to listen on interface 127.0.0.2 and connect to '\\127.0.0.2\sharename'. This is all that is necessary.
Windows XP: same as for Windows 2000, but before using the forwarded share, the local (client's) Windows file sharing server needs to be stopped via 'net stop server'. To disable it permanently, run 'sc config lanmanserver start= disabled'. To re-enable it at a later time, run 'sc config lanmanserver start= auto'. Note the space between 'start= ' and the following parameter - sc will fail without it.

If you want to avoid disabling the file sharing server on the client machine because you want to retain remote access to the client machine's shared resources, there is another alternative. You can install the Microsoft Loopback Adapter according to instructions relevant to your version of Windows:

If using the Microsoft Loopback Adapter, remember to setup your SSH client appropriately: use the Loopback Adapter's IP instead of 127.0.0.1 or 127.0.0.2. If you assigned the Loopback Adapter the IP address 10.10.10.10, configure a client-to-server port forwarding rule to listen on 10.10.10.10, port 139; then you can connect to '\\10.10.10.10\sharename'.

If the instructions on this page fail for you, try some of the file share tunneling tips contributed by our users.

Note that, in all cases, you will not be able to browse to the sharing-provider machine via point-and-click - the network path needs to be typed in manually.

Step-by-step instructions

Follow these steps if you wish to get quickly up and started with Windows file sharing over SSH. It is advised that you try to understand what is being done by each one of the steps presented. The difference between understanding and not understanding is frequently the difference between a security measure which works and one that only appears to.

On the server machine: (the file-sharing provider)

Install WinSSHD on the server (the machine that has the resources you wish to access with Windows file sharing).
No changes to the default WinSSHD configuration are required to use Windows file sharing over SSH. You may wish to make changes to the default WinSSHD configuration later on, to restrict what WinSSHD features are accessible to remote users. However, for the time being, keep your WinSSHD settings at default until your file sharing over SSH is up and running.
Apart from installing WinSSHD, the only thing you need to do on the server is ensure that there is a Windows account which you can use to log on locally, and which you are comfortable using through Tunnelier and WinSSHD. If such an account does not yet exist, create one and use it to log on for the first time through the local Windows console to make sure all settings for the new account are initialized.
Start the WinSSHD service from the WinSSHD Control Panel.

On the client machine:

If the client is running Windows XP or 2003 and you wish to retain the ability to share the client's resources, install and configure the Microsoft Loopback Adapter.
Install Tunnelier on the client (the machine from which you wish to be accessing the server machine's shared resources).
Configure the following settings on the Login tab in Tunnelier. Click also the 'Help' link on the Login tab for help with any of these settings.
1. Host: The IP address or DNS name of the server that you are accessing.
2. Port: You will normally use the default value, 22. This must match the port that WinSSHD is listening on. If you have made no changes to the default WinSSHD configuration to change the port it is listening on, use 22.
3. Username: The Windows account name with which to log into the server. This must be a valid Windows account name with local logon permissions on the side of the server.
4. Password: The password with which to log into the server, belonging to the account name specified by Username.
5. Store encrypted password in profile: You may optionally wish to enable this setting so that you will not be asked to reenter the password each time when logging in after Tunnelier has been restarted.
In the C2S Forwarding tab in Tunnelier, add a new entry and configure the following settings for this entry. Click also the 'Help' link on the C2S Forwarding tab for help with any of these settings.
1. Status: This will be 'enabled' by default, leave it that way.
2. Listen interface: The default value is 127.0.0.1. If the client machine is running Windows XP, leave this as it is; you will need to uninstall file and printer sharing on the client machine anyway. If the client machine is running Windows 2000, change this to 127.0.0.2 so that you will not need to uninstall file and printer sharing.
3. List. Port: 139.
4. Destination Host: set this to the interface on which the file sharing server is listening for SMB connections. Setting this to 'localhost' or 127.0.0.1 will not work because the file sharing server is usually listening on a specific interface rather than all interfaces, so it will not be possible to go through the loopback connection. To determine the interface where the file sharing server is listening, execute 'netstat -an' on the server and examine the output for a line like 'xxxxxx:139 ... LISTENING'. The xxxxxx is the IP address that you need to enter in this field. Normally this will be the IP address associated with the server's main ethernet adapter.
5. Dest. Port: 139.
Click the Login button in Tunnelier and observe the log area for any errors. If the session is established without errors, the SSH setup is running.
If you are running Windows XP, you will now need to uninstall (not just disable, but completely uninstall) file and printer sharing on the client machine. This can be done through Network Connections : (each connection) : Properties - select 'File and Printer Sharing' in the list box and press the Uninstall button. This needs to be done for each active network connection on the client machine.
If you are using earlier versions of Windows (this is confirmed for Windows 2000 but is likely to apply to the 9x/Me series as well), you will not need to uninstall file and printer sharing if you specified 127.0.0.2 as the Tunnelier C2S rule listening interface (above).
Once the above steps have been completed, you will be able to connect securely to the shared resources on the server machine using syntax such as \\127.0.0.1\sharename or \\127.0.0.2\sharename, respectively. This will work as long as the Tunnelier SSH connection remains established.
You can make sure that your file sharing connections are going through Tunnelier by checking the Tunnelier log area for a message saying 'Accepted client-to-server connection from ... to ...:139' corresponding to each connection attempt you make. Likewise, when your file sharing connection closes, Tunnelier should output a log message stating 'Closing client-to-server forwarding channel from ... to ...:139'.

Troubleshooting

Please see our contact and support page for more information and links to documents about how to go about resolving problems with Tunnelier and WinSSHD.

Chapter 2.6.1

Loopback Adapter file share tunneling: XP, 2003

The following instructions document how the Microsoft Loopback Adapter can be installed and configured for use with file share tunneling on Windows XP and 2003:

Installing the Loopback Adapter:
1. Open Start, Control Panel, Add Hardware.
2. Click Next on the introduction dialog box.
3. Select 'Yes, I have already connected the hardware' and click Next.
4. Scroll to the bottom of the list of hardware, select 'Add a new hardware device', then click Next.
5. Select 'Install the hardware that I manually select from a list (Advanced)', then click Next.
6. Select 'Network adapters', then click Next.
7. Select 'Microsoft' as the manufacturer, select 'Microsoft Loopback Adapter' as the adapter, then click Next.
8. Click Next to confim the installation.
9. Click Finish to complete the installation.
Configure the newly created adapter:
1. Open Start, Control Panel, Network Connections.
2. Select the newly created connection (should be named 'Local Area Connection N', where N is its order number).
3. Right click on the selected connection and choose Properties from the menu.
4. Confirm that 'Microsoft Loopback Adapter' (or 'Microsoft Loopback Adapter #N') is displayed in the 'Connect Using:' field. If it isn't, return to step 2 and retry properties for another adapter.
5. Uncheck (disable) everything except 'Internet Protocol (TCP/IP)'.
6. Select 'Internet Protocol (TCP/IP)', then click Properties to open 'Internet Protocol (TCP/IP) Properties'.
7. Select 'Use the following IP address:' and fill in the 'IP address:' and 'Subnet mask:' fields (e.g. 10.10.10.10, 255.255.255.0).
8. Click Advanced to open 'Advanced TCP/IP Settings'.
9. Switch to WINS and select 'Disable NetBIOS over TCP/IP'.
10. Click OK to close 'Advanced TCP/IP Settings'.
11. Click OK to close the 'Internet Protocol (TCP/IP) Properties'.
12. Optionally (on XP only) uncheck (disable) 'Notify me when this connection has limited or no conectivity' to remove the connection warning icon from the system notification area.
13. Click OK to close the connection properties.

If you later want to uninstall the Microsoft Loopback Adapter (once it is not needed any more for the forwarding of a Windows file share), you can uninstall it using Control Panel > System > Hardware > Device Manager.

Chapter 2.6.2

Loopback Adapter file share tunneling: Win2K

The following instructions document how the Microsoft Loopback Adapter can be installed and configured for use with file share tunneling on Windows 2000:

Installing the Loopback Adapter:
1. Start, Settings, Control Panel, Add/Remove Hardware.
2. Click Next on the introduction dialog box.
3. Keep 'Add/Troubleshoot a device' selected and click Next.
4. Select 'Add a new device', then click Next.
5. Select 'No, I want to select the hardware from the list', then click Next.
6. Select 'Network adapters', then click Next.
7. Select 'Microsoft' as the manufacturer, select 'Microsoft Loopback Adapter' as the adapter, then click Next.
8. Click Next to confim the installation.
9. Click Finish to complete the installation.
Configure the newly created adapter:
1. Open Start, Settings, Control Panel, Network and Dial-up Connections.
2. Select the newly created connection (should be named 'Local Area Connection N', where N is its order number).
3. Right click on the selected connection and choose Properties from the menu.
4. Confirm that 'Microsoft Loopback Adapter' (or 'Microsoft Loopback Adapter #N') is displayed in the 'Connect Using:' field. If it isn't, return to step 2 and retry properties for another adapter.
5. Uncheck (disable) everything except 'Internet Protocol (TCP/IP)'.
6. Select 'Internet Protocol (TCP/IP)', then click Properties to open 'Internet Protocol (TCP/IP) Properties'.
7. Select 'Use the following IP address:' and fill in the 'IP address:' and 'Subnet mask:' fields (e.g. 10.10.10.10, 255.255.255.0).
8. Click Advanced to open 'Advanced TCP/IP Settings'.
9. Switch to WINS and select 'Disable NetBIOS over TCP/IP'.
10. Click OK to close 'Advanced TCP/IP Settings'.
11. Click OK to close the 'Internet Protocol (TCP/IP) Properties'.
12. Click OK to close the connection properties.

If you later want to uninstall the Microsoft Loopback Adapter (once it is not needed any more for the forwarding of a Windows file share), you can uninstall it using Control Panel > Add/Remove Hardware (click Next, then 'Uninstall/Unplug a device', then 'Uninstall a device').

Chapter 2.6.3

Loopback Adapter file share tunneling: NT4

The following instructions document how the Microsoft Loopback Adapter can be installed and configured for use with file share tunneling on Windows NT4:

Open Start, Settings, Control Panel, Network.
Switch to the Adapters tab, then click 'Add...'
Leave the default '802.3' Frame Type and click OK. (802.3 is CSMA/CD - ETHERNET.)
A 'Windows NT Setup' dialog will pop up saying that the Windows NT4 CD is required. Insert the CD and click Continue.
Once back in Network properties, switch to the Bindings tab.
Change 'Show bindings for:' to 'all adapters'.
Open the newly created adapter tree (should contain names as '[N] Loopback Adapter', where N is the order number).
Disable everything except 'TCP/IP Protocol' in the subtree.
Switch to the Protocols tab.
A 'Network Settings Change' dialog pops up. Click Yes to save changes.
The 'Microsoft TCP/IP Properties' dialog opens. Change 'Adapter:' to the newly created adapter (should be '[N] MS Loopback Adapter').
Select 'Specify an IP address' and fill in the 'IP address:' and 'Subnet mask:' fields (e.g. 10.10.10.10, 255.255.255.0).
Click OK to close 'Microsoft TCP/IP Properties'.
Click Close to close Network.
Restart the computer so that the new settings will take effect.

If you later want to uninstall the Microsoft Loopback Adapter (once it is not needed any more for the forwarding of a Windows file share), you can uninstall it in Control Panel > Network > Adapters.

Chapter 2.7

Securing WinVNC With SSH

VNC is a free client/server system which allows you to view a computing 'desktop' environment not only on the machine where it is running, but from anywhere on the Internet and from a wide variety of machine architectures.

You can combine WinVNC and an SSH port forwarding client/server pair such as WinSSHD and Tunnelier to form a secure solution for remote GUI login. Suppose you install a VNC server on machine A, and the SSH server on machine B. Machine A and machine B can be the same machine, and should generally be as close as possible, because only the connection between the VNC viewer and machine B will be secured; the connection between machine A and machine B will be unprotected. In order to securely access the VNC server from a client machine, you need to perform the following steps:

Equip the client machine with an SSH port forwarding client. Configure this client to connect to the SSH server on machine B, and to forward connections that come to port 5900 on the client machine to port 5900 on machine A. In SSH terminology, this is client-to-server port forwarding, or 'local' forwarding. If you intend to use a VNC display other than 0, you should alter the port numbers appropriately: the VNC port number is 5900 plus the display number, e.g. 5905 for display 5.
Configure the VNC viewer to connect to localhost. If you configured the SSH client to listen on a port other than 5900, you also need to specify the display number. E.g., specify 'localhost:5' if the SSH client is listening on port 5905.
If the SSH and WinVNC servers both reside on the same computer, you will need to enable local loopback connections in WinVNC. See the WinVNC documentation - look for the AllowLoopback keyword under" Advanced Options.

See also Making VNC more secure using SSH (alternate links 1) for a lengthier description of how to setup SSH port forwarding for VNC.

Chapter 2.8

What you need to know about the Internet

Our products can be used in ways that don't require much knowledge about the internet. You can just type in the address of the server you're connecting to, open an SFTP window and start transferring files. However, if you will be using the more advanced features of our products, such as tunneling, you will need to understand the basics of how the Internet is structured. This guide is an attempt at relaying some of that understanding.

This guide is composed of the following sections:

IP addresses
DNS names
Subnets
Types of IP addresses and subnets
TCP and UDP
Direction of TCP connections
Ports
Connecting to the internet from office
Connecting to the internet from home
Dynamic IP address issues
Virtual servers - port forwarding at the router
Firewalls

IP addresses

Every computer connected to the internet has an Internet Protocol or IP address which identifies the computer on the internet. In the currently most widely used version of the Internet Protocol - version 4 - IP addresses are 4 bytes long and are expressed in the form nn.nn.nn.nn. Each nn is a number between 0 and 255.

When you connect to a web server to browse a web page, the DNS name of the web server, e.g. www.bitvise.com, is automatically translated by the software in your machine to an IP address in the nn.nn.nn.nn form. This address is then used to connect to the actual web server.

For example, the IP address of the server hosting fogbugz.bitvise.com at the time of this writing is 70.85.217.69. Our primary website, on the other hand, is hosted on several servers, and their IP addresses are 207.155.248.18, 207.155.248.31, 207.155.248.122 and 207.155.252.47.

In a Windows Command Prompt session, you can discover the IP addresses associated with DNS names using the nslookup command: e.g. 'nslookup www.bitvise.com'.

DNS names

IP addresses are difficult to remember, so the internet provides a translation service which translates memorable names into associated IP addresses. This facility is called the Domain Name System or DNS. You use DNS implicitly every time you type in an address such as 'www.bitvise.com' - your browser asks your operating system for translation into an IP address, and the operating system either returns a cached result, or inquires with a DNS server operated by your ISP. This server in turn either returns a cached result or inquires with another DNS server.

Subnets

No computer is directly connected to every other computer on the internet. Instead, each computer is a member of one or more subnets. Subnets, in turn, are connected to each other by machines called routers or gateways, which belong to multiple subnets, forwarding internet traffic from one subnet to the other and reverse.

In order to successfully communicate with other computers throughout the internet, your computer must know what subnet it is part of, so that it knows what IP addresses are outside your local subnet and must be relayed through the gateway. In addition, your computer must of course also know the IP address of the gateway.

Typically, a subnet is a group of consecutive IP addresses, such as all IP addresses from 11.22.33.0 to 11.22.33.255. This is commonly expressed in either of two formats:

The subnet mask format. Here, the subnet is expressed as 11.22.33.0 with subnet mask 255.255.255.0. The subnet mask indicates what bits of the subnet IP address indicate the actual subnet, and what bits are variable, indicating individual computers in the subnet. A byte consists of 8 bits, and 255 is 1111 1111 in binary. Therefore, 255.255.255.0 means that the first 3 bytes of the subnet IP address (11.22.33) indicate the actual subnet, and the last byte can be variable (and indicates computers in the subnet). If the subnet mask were 255.255.0.0, that would mean that the last two bytes are variable.
The significant bits format. Here, the subnet is expressed as 11.22.33.0/24, which means subnet 11.22.33.0 with 24 significant bits. The 24 means that the first 24 bits of the subnet mask are 1, and all the following bits are 0. Thus, /24 is equivalent to a subnet mask of 255.255.255.0. /16 is equivalent to a subnet mask of 255.255.0.0. And because there are just 32 bits in an IP address, /32 indicates an IP address with no variable part: a fixed, constant IP address.

Our software expresses subnets using the significant bits format.

Types of IP addresses and subnets

There are three major types of IP addresses (or subnets) that you need to be aware of.

Public IP addresses. Most IP addresses in the 32-bit address range have the purpose of uniquely identifying a computer on the internet. The IP address 207.155.248.18, for example, is a public IP address that uniquely identifies one of the servers hosting the www.bitvise.com website (and others). This is the type of IP address through which a server must be reachable in order to be accessible to computers throughout the internet.
Private subnets. Special ranges of the 32-bit IP address range have been set aside for use in private networks, where the computers in such a network do not need to be directly accessible from the internet as servers (but may nevertheless access the internet through a gateway, as clients). These ranges include:
- 10.0.0.0/8 (addresses from 10.0.0.0 to 10.255.255.255)
- 172.16.0.0/12 (addresses from 172.16.0.0 to 172.31.255.255)
- 192.168.0.0/16 (addresses from 192.168.0.0 to 192.168.255.255)
Special IP ranges. There are several special purpose IP ranges, but the one you need to know about is 127.0.0.0/8 (addresses from 127.0.0.0 to 127.255.255.255). This is the local loopback range and is used to connect two programs running on the same machine. Any address in this range can be used for this kind of purpose, but the most commonly used are 127.0.0.1 and 127.0.0.2. The special DNS name 'localhost' translates to 127.0.0.1.

TCP and UDP

The Internet Protocol itself is a relatively rudimentary protocol which provides only the capability of delivering small chunks of data to other computers. The Internet Protocol does not provide reliability: chunks of data that are sent using the Internet Protocol may be lost. They also may arrive in an order different to the order in which the chunks were sent.

For some types of data transfer, the (un)reliability afforded by the Internet Protocol is fine. When streaming video, for example, it does not matter if chunks that make up intermediate frames of the video are lost. What matters is that most of the data arrives relatively quickly, allowing the video to be played with reasonable quality and on the fly. The User Datagram Protocol, or UDP, is a simple protocol layered on top of the Internet Protocol that provides this level of reliability. UDP is used for purposes such as relaying video and audio streams as well as for networked games; all environments where responsiveness and fast delivery is more important than perfect reliability.

For other types of data transfer, however, this level of reliability is not enough. When transferring a file, for example, you want to transfer all of its contents in perfect order and integrity; you don't want any chunks of it to accidentally be lost. When accessing a web page, likewise, you want all the text to be transferred without error. Data transfers that require this higher level of reliability use the Transmission Control Protocol, or TCP. Like UDP, TCP is a protocol layered on top of the Internet Protocol, but it is more complex than UDP: it contains mechanisms to ensure that data is received in order and that, if any chunks are lost, they are resent. The realiability provided by TCP has costs in terms of responsiveness. Before any data can be sent using TCP, the two computers must engage in a short back-to-forth to establish a TCP connection. If any data are lost during transmission, delivery of subsequent data awaits until the data that were lost are retransmitted and delivered. When there is a high rate of data loss on a connection, this may cause transmission to be jerky.

The majority of widely known protocols used on the internet are layered on top of TCP. These include:

the Simple Mail Transfer Protocol (SMTP), used for email delivery;
the Post Office Protocol (POP) and IMAP, used for email retrieval;
the Hypertext Transfer Protocol (HTTP), used for accessing websites;
as well as, of course, the Secure Shell protocol (SSH), which our products are about.

Direction of TCP connections

TCP connections are like phone calls: they are always initiated by one party and accepted (or not) by the other. The computer that originates the TCP connection is usually the client, and the computer that accepts it is usually the server. Sometimes, notably in the FTP protocol, a secondary TCP connection will be established in the reverse direction, from the server to the client. But, in protocols other than FTP, connections are almost always initiated by the client.

Regardless of the direction in which a TCP connection is established, data can always flow both ways. However, the direction of the TCP connection matters because it determines who the initiating party is, and is also used by network components to impose rules on whether a connection can be established.

Ports

In order to handle multiple simultaneous connections with the same computer, your computer must be able to distinguish them. To do so, each connection is assigned two port numbers, one at each end point of the connection. A connection is then uniquely identified with four pieces of information: (1) local address, (2) local port, (3) remote address, (4) remote port. Valid port numbers are between 1 and 65535. The party that originates a TCP connection usually selects a local port number at random. On the other hand, the port number of the party that accepts the connection must be known in advance by the party that originates the connection. You can confirm this by executing 'netstat -n' from a Windows Command Prompt just after loading a web page in your browser.

For example, this excerpt from 'netstat -n' output was taken just after opening www.bitvise.com in a browser.

Proto Local Address Foreign Address State
TCP 10.10.10.123:21681 207.155.248.122:80 ESTABLISHED

The above output indicates an established TCP connection with local address 10.10.10.123, local port 21681, remote address 207.155.248.122 and remote port 80. The connection was initiated by the local machine, therefore the local port number 21681 was randomly selected, whereas the remote port number 80 is the well-known HTTP port. This is the port where the vast majority of web servers accept connection, so even when access to other ports is blocked, connections to port 80 will very likely be permitted.

Other well-known destination ports are:

21 - FTP (control connection)
22 - SSH
23 - Telnet
25 - SMTP
80 - HTTP
110 - POP3
143 - IMAP4
443 - HTTPS (HTTP over TLS or SSL)
1080 - SOCKS proxy

On Windows, a more exhaustive list of well-known ports can be found in the file \Windows\System32\Drivers\etc\services (open it with Notepad).

Connecting to the internet from office

In an office environment, your computer will most likely be connected to a subnet in one of the private address ranges. This means that your computer will have an IP address not unique throughout the internet, so it cannot communicate with other computers on the internet directly. However, the network administrators at your office have most likely applied one of the following solutions to allow you to access the internet.

Network address translation (NAT). In this setup, your computer directs all traffic destined to the internet through a gateway in your local subnet. This gateway has a public IP address which is unique and can be used for internet addressing. The gateway substitutes its own IP address and port in place of your computer's. When chunks of data arrive in reply, the gateway knows from the port number in the data that they must be forwarded to your computer and local port.
In this setup, your computer is led to believe that it is present on the internet with its private subnet IP address; but it isn't. The gateway is present on the internet and represents all computers in the subnet with its own public IP. All connections initiated to the internet by computers on the subnet appear to outside observers as coming from the gateway's public IP address.
Proxy. In this setup, your computer cannot initiate connections to the internet directly. Instead, applications on your computer must contact one of several types of proxy servers residing on your local subnet, and ask the proxy server if it would kindly relay a connection to the outside. This is conceptually similar to NAT. However, whereas NAT works for all applications on your machine and requires from them no special awareness, the proxy setup works only with those applications which can connect to the internet through the proxy. The proxy setup also affords administrators more control: they can more easily restrict and monitor your traffic and permit or deny access selectively based not just on port numbers, but the content being accessed and protocols being used.

There is also a number of office environments where each computer has a separate, own public IP address. These are simple and involve no NAT or proxy servers as outlined above.

Connecting to the internet from home

From home, you usually connect to the internet through a modem - whether it is phone, cable, ISDN or DSL. In any case, you can either hook the modem directly to your computer; or, if you have multiple computers, you can buy a router, connect the router to your modem and your computers to the router.

If you use a router, the machines connected to it are assigned addresses in a private subnet, and the router performs Network Address Translation to allow your machines to access the internet.
If you connect the modem to your machine directly, the computer gets a public IP address directly accessible from the internet. If you then connect other machines to this machine (through a second network interface), those machines are joined to a private subnet. The directly connected machine then performs Network Address Translation to allow the other computers to access the internet.

In most cases, you will be provided a single public IP address by your internet provider. Sometimes this IP address will be fixed; this is called a static IP address. In other situations, the IP address will periodically change; this is called a dynamic IP addres. With dial-up modems, you will get a different public IP address every time you dial up. With DSL and cable modems, your IP address may change at a predefined time every day or night.

Dynamic IP address issues

The following issues correspond with a continuously changing IP address.

Whenever your public IP address changes, all ongoing TCP connections to and from your machine are terminated and must be reestablished using the new IP.

Since the IP address of your computer is unpredictable, it is difficult for others to connect to it. If you want to host any kind of network-accessible service on your machine, you need to either use a dynamic DNS service; this works by allocating you a DNS name which is regularly updated to reflect your changing IP address; or you need to implement a more pedestrian solution, such as configuring a program on your computer to periodically connect to another server and store your current IP address there, making it available for retrieval.

If you want to host a service on your home machine and find that your IP address changes periodically, the best way around this problem is to ask your ISP to grant you a static IP. They will frequently agree to do this free of charge. If this is unavailable, you can use a dynamic DNS service.

Virtual servers - port forwarding at the router

If you want to make a server accessible from the internet, but the computer on which the server will be based has only a private subnet IP addresses, there is a solution. Usually, the router which connects the private subnet to the internet can be configured to forward all incoming connections on a certain port to one of the computers inside the private network. This is called port forwarding (not the same thing as SSH port forwarding) or a 'virtual server' facility (although the server is quite real; it's just its IP address that is not).

This setup generally works just fine, but there is one thing to remember. The IP address by which the server is known to internet clients is not the IP address that the server machine actually has. This distinction between the public IP address at the router, and the private IP address of the actual server machine inside, frequently arises in SSH connection tunneling, leading to incorrect configuration if not properly understood.

Firewalls

Modern computers run a large number of local services (such as Windows file and printer sharing) which accept connections on various port numbers, but are meant to be accessible only from locally trusted subnets. Preventing the wider internet from accessing these services in possibly malicious ways is the purpose of ingress firewalls.

In organizations, gateways that connect the local subnet to the internet usually feature an ingress firewall. This firewall should normally be configured to allow no connections into the subnet, except connections to servers that must accept connections from the internet.

At home, your ISP will usually not protect your PC from malicious access from the internet. Instead, this task must be performed by a firewall installed on your home router, or if your computer is connected to the internet directly, a software firewall in your machine. Windows XP comes equipped with such a firewall; you should use it. Software firewall solutions are available for earlier versions of Windows.

There is another type of firewall called an egress firewall, or a firewall that filters outbound connections from your machine to the internet. This is generally software which tries to control what programs on your machine access the internet. This is intended to block malicious software from doing too much damage after it has already infected your computer. However, cleverly written malware can fool an egress firewall like this with fairly simple and straightforward deceptions. The only real medicine against malware is therefore to prevent it from infecting your computer in the first place.

Bitvise WinSSHD: Printable Documentation

Table of Contents

Part 1: WinSSHD Users' Guide

Part 2: Tutorials

Part 1. WinSSHD Users' Guide

Chapter 1.1

Installing WinSSHD

Unattended installation

Chapter 1.2

Upgrading from a previous version

Unattended upgrade

Chapter 1.3

Starting WinSSHD and monitoring activity

Monitoring

Logging

Chapter 1.4

Opening WinSSHD to the internet

Necessary preparation

WinSSHD 5.06 and later

WinSSHD 5.05 and earlier

Chapter 1.5

Connecting for the first time

Chapter 1.6

Configuring groups and accounts in WinSSHD

Windows groups and accounts

Virtual groups and accounts

Chapter 1.7

Using WinSSHD in a domain

Domain Order

Chapter 1.8

Network vs. interactive logon

Selecting the right logon type

Chapter 1.9

Setting up public key authentication

Chapter 1.10

Fine-grained tunneling restrictions

Connect rules

Listen rules

Example 1: Permit a client-to-server destination

Example 2: Permit a server-to-client binding

Chapter 1.11

Using WinSSHD in a cluster

Password Cache

Chapter 1.12

Scriptable configuration with wcfg

Chapter 1.13

Additional Advanced Modes of Configuration and Usage

Chapter 1.14

Useful resources and utilities

Part 2. Tutorials

Chapter 2.1

Frequently Asked Questions about Using WinSSHD

Personal Edition

Getting It Up and Running

File Transfer Issues

Public Key Authentication

Account Settings

Usage

Contacting Support

Chapter 2.2

Using WinSSHD as SFTP, SCP file server

Chapter 2.3

Securing Your WinSSHD Settings

Disabling features you don't want

Restricting access to chosen accounts

Limiting directory access

Ensuring strong authentication

Chapter 2.4

A short guide to SSH port forwarding

Chapter 2.5

Single-Click Remote Desktop Forwarding

Securing Remote Desktop With SSH

Listening Port on XP vs. Win2K and Earlier

Connecting to Localhost on XP prior to SP2

Step-by-step instructions

Troubleshooting

Chapter 2.6

Securing Windows File Sharing With SSH

Step-by-step instructions

Troubleshooting