Bitvise SSH Server: Printable Documentation

Table of Contents

Part 1: Bitvise SSH Server Users' Guide

Chapter 1.1: Installing

Chapter 1.2: Upgrading

Chapter 1.3: Starting and monitoring

Chapter 1.4: Connecting for the first time

Chapter 1.5: Opening Bitvise SSH Server to the internet

Chapter 1.6: Groups and accounts

Chapter 1.7: Windows domains

Chapter 1.8: Network/interactive logon

Chapter 1.9: Public key authentication

Chapter 1.10: Tunneling restrictions

Chapter 1.11: Master/slave synchronization and clusters

Chapter 1.12: Scriptable config - BssCfg

Chapter 1.13: Advanced modes of use

Chapter 1.14: Log files and MS Log Parser

Chapter 1.15: Resources and utilities

Part 2: Tutorials

Chapter 2.1: Frequently asked questions

Chapter 2.2: Configuring Bitvise SSH Server for SFTP and SCP

Chapter 2.3: Securing Bitvise SSH Server

Chapter 2.4: Public keys in SSH

Chapter 2.5: Port forwarding guide

Chapter 2.6: Web browsing over SSH

Chapter 2.7: X11 forwarding

Chapter 2.8: Tunnel Remote Desktop

Chapter 2.9: Tunnel Windows shares

Chapter 2.10: Tunnel WinVNC

Chapter 2.11: What you need to know about the internet

Part 1. Bitvise SSH Server Users' Guide

Chapter 1.1

Installing Bitvise SSH Server

To install Bitvise SSH Server, 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 SSH server 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 Bitvise SSH Server 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:

  BvSshServer-Inst.exe -?

For example, if you wished to install Bitvise SSH Server on a fresh machine and start it immediately afterwards, you might execute the following:

  BvSshServer-Inst.exe -defaultSite -activationCode=0123...6789
  net start BvSshServer

To apply a ready-made configuration file as part of the installation process, add the '-settings=...' parameter and specify the file from which Bitvise SSH Server should load its configuration. This file can be created by exporting the settings of an existing installation from its Bitvise SSH Server Control Panel.

To uninstall from the command line, copy the uninst.exe program in the Bitvise SSH Server installation directory to another temporary location, and execute it from there as follows:

  uninst.exe "Bitvise SSH Server" -unat

If you are installing a single Bitvise SSH Server 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 Bitvise SSH Server (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 SSH server version is installed. 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.

In case you must downgrade. During a downgrade, your SSH server settings will be reset. However, recent Bitvise SSH Server versions automatically create backups of your settings when they are modified, and you can revert to one of these backups if you decide to downgrade. The backups are located in the Config subdirectory of your SSH server installation directory.

Older WinSSHD versions (e.g. 4.xx) do not maintain backups. Before upgrading from such a version, you should use the WinSSHD Control Panel to export your settings to a file, in case you later decide to downgrade.

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. If your upgrade access has expired, log into your License Overview to purchase an upgrade extension, and acquire a new activation code.

If the purchasing process in your organization is slow, we do recommend that you initiate the upgrade extension process well before you plan to upgrade to a version not covered by your current upgrade access.

Unattended upgrade

It is possible to upgrade Bitvise SSH Server in unattended mode, without having to explicitly remove the previous version. This can be done by executing the Bitvise SSH Server installer with command line parameters:

  BvSshServer-Inst.exe -installDir="C:\Program Files\Bitvise SSH Server"

Alternately:

  BvSshServer-Inst.exe -site="Bitvise SSH Server"

You will also need to supply the -acceptEula parameter to indicate acceptance of the Bitvise SSH Server End User License Agreement.

It is possible to use the installer for unattended installation to a named site. In this case, use the '-site' parameter (instead of '-installDir') and specify the name of the site desired.

In the latest Bitvise SSH Server versions, the installer will automatically stop the SSH service and Control Panel if they were running prior to the upgrade. In older WinSSHD versions, it may be necessary to execute a "net stop WinSSHD" command before the installer (and close the WinSSHD Control Panel, if open).

After a successful upgrade, the command "net start BvSshServer" can be executed to start the SSH server.

Upgrading Bitvise SSH Server when it provides exclusive access

Sometimes, Bitvise SSH Server is installed on machines where it provides exclusive access to those machines, and no other ports are open. In such situations, bringing the SSH server down for maintenance or an upgrade can render the machine inaccessible if something goes wrong.

In such situations, we recommend installing an additional SSH server installation as a named site. The additional SSH server installation should accept connections on a different port than the primary installation. This port should be accessible through any routers and firewalls. When maintenance or upgrade is needed on the primary installation, access the server through the alternate installation, and vice versa.

Note that multiple Bitvise SSH Server installations running directly on the same OS installation do not constitute an additional machine, and are covered by the same license. Therefore, no additional purchase is necessary for the maintenance installation.

Chapter 1.3

Starting Bitvise SSH Server and monitoring activity

Bitvise SSH Server can be started and stopped in the following ways:

Monitoring

The Bitvise SSH Server Control Panel features a Session tab, which shows SSH sessions currently active on the server.

Since version 5.06, the Bitvise SSH Server 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 SSH Server 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 Bitvise SSH Server log files.

Logging

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

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

Chapter 1.4

Connecting for the first time

If you are new to Bitvise SSH Server, 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 the SSH server 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, Bitvise SSH Server 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 the SSH server. 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 Bitvise SSH Server with an SSH client for the first time, log in with the username and password of a Windows account that exists on the machine where the SSH server 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 Bitvise SSH Server, 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, including SSH software, should be kept up-to-date to minimize exposure to security flaws.

Clients that are known to work well with Bitvise SSH Server include Bitvise SSH Client (which works best), as well as CuteFTP Pro, Tectia, F-Secure / WRQ / Reflection, VanDyke (SecureCRT, SecureFX), OpenSSH, PuTTY, FileZilla, and many others. WinSCP works well in SFTP mode.

Chapter 1.5

Opening Bitvise SSH Server to the internet

Bitvise SSH Server 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 Bitvise SSH Server to the internet, other network components must first be configured. The most prominent such components are the firewall on the machine where the SSH server is running, and the router on the LAN to which this machine is attached.

Necessary preparation

Before you open Bitvise SSH Server to the internet, perform the following important steps:

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

Bitvise SSH Server (WinSSHD) 5.06 and later

Since version 5.06, you can configure Bitvise SSH Server to perform the above tasks automatically.

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

Configuring groups and accounts in Bitvise SSH Server

Immediately after initial installation, when started under original default settings, Bitvise SSH Server will accept password, NTLM or Kerberos-based login to any Windows account that has Windows permissions log into the machine where the SSH server is running.

When a Windows account user logs in, Bitvise SSH Server will impersonate the security context of that Windows account throughout the user's SSH session. Under default settings, the server will allow any successfully logged on user to take any action that the user is permitted by Windows and file system permissions. Such actions include accessing the terminal shell, running a program, uploading and downloading files, or connecting to another machine using SSH port forwarding.

Most administrators will find it desirable to configure Bitvise SSH Server in a way that restricts users' access further. The groups and accounts sections of Bitvise SSH Server's Advanced settings provide the means for this configurability. The groups and accounts in SSH server settings are an additional layer of security, imposed by the SSH server on top of the Windows permission system. Bitvise SSH Server settings do not replace Windows permissions, but provide complementary settings which Windows does not provide on its own.

Additionally, virtual groups and virtual account settings provide the means to add users in Bitvise SSH Server 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 Bitvise SSH Server configuration for Windows groups and accounts is very straightforward. It consists of a single 'Everyone' group. In a default configuration, the SSH server settings for the Everyone group apply to all Windows accounts that log in via SSH.

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

This means that:

Virtual groups and accounts

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

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

Chapter 1.7

Using Bitvise SSH Server in a domain

Bitvise SSH Server fully supports environments with domain, domain forest, and Unix realm authentication. Since version 5.50, changes to Active Directory settings are no longer necessary to authenticate against the SSH server, except when using:

In these cases, Active Directory permissions may still need to be modified, as described below.

Active Directory Permissions for Password-less Logon

If you would like to use Windows domain accounts with public key authentication, or as backing accounts for virtual accounts; and if you do not wish to configure passwords for these domain accounts in the SSH server's password cache; then you will instead need to ensure that the SSH server has read permissions to user data in the Active Directory.

A default Active Directory installation may grant the necessary read permissions through the Active Directory group named "Pre-Windows 2000 Compatible Access". If these default settings have been changed, a permissions issue might arise when trying to use domain accounts with password-less logon.

If the SSH server's log files indicate permission-related issues when trying to use domain accounts with password-less logon, grant the necessary read permissions as follows:

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

Windows domain order

Since version 5.50, Bitvise SSH Server no longer requires the Domain Order setting to enable login with non-fully-qualified usernames. Domain users are now able to log in, without providing a domain name as part of their username, using default SSH server settings.

The Windows domain order feature is still supported for administrators who wish to explicitly configure the order in which non-fully-qualified usernames should be looked up, to ensure predictable results.

Loading Windows Profiles

When configuring Bitvise SSH Server to provide SFTP and SCP access for domain users, users may have large Windows profiles that will be loaded before the user's file transfer session can start. Very large profiles may delay session startup. If you wish to prevent the SSH server from loading Windows profiles, please note that any of the following conditions will cause Bitvise SSH Server to load a user's Windows profile:

If you wish to prevent the SSH server from loading Windows profiles, you will need to make sure that none of the above conditions apply.

Chapter 1.8

Network vs. interactive logon

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

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 in via SSH 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, which are internal to Bitvise SSH Server, instead of creating a separate account in Windows for each user.

Chapter 1.9

Setting up public key authentication

If your SSH client supports it, you can use public key authentication to log into Bitvise SSH Server. On Windows, we recommend Bitvise SSH Client, which 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 client authentication. The procedure for generating the keypair depends on the client software being used:

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:

Once your public key file has been exported, transfer it to the machine where Bitvise SSH Server is installed, or the machine from which you manage the SSH server remotely using Bitvise SSH Client. If you are exporting the public key from Bitvise SSH Client, and you are also using the same client to administer the SSH server remotely, no transfer is necessary. In this case, use the "Bitvise SSH Server Control Panel" feature from the SSH Client.

Open Bitvise SSH Server settings - either Easy or Advanced - and open the "Public keys" link from the Windows or virtual account settings entry for which you're importing the key. If an entry for the user you are configuring is not already present, add it. Once you click the "Public keys" link, a key management window will open. Use this window to import the public key.

Common mistakes: Make sure that you don't try to import the client's key into the server's host key management interface. The host key management interface is accessed directly from the "Server" tab of the Bitvise SSH Server Control Panel, and is intended to manage keypairs that authenticate the server. These keypairs are separate and unrelated to client authentication.

Chapter 1.10

Fine-grained tunneling restrictions

'Tunneling' or 'port forwarding' refers to the ability of an SSH client (a) to have the SSH server initiate a TCP/IP connection to another server on the SSH client's behalf (called client-to-server tunneling), or (b) to have the SSH server 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, Bitvise SSH Server provides two easy ways to control a user's or group's access to tunneling. In the Bitvise SSH Server 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 the SSH server to initiate outbound connections. Disable the second and the user will not be able to instruct the SSH server to listen for connections to forward to the SSH client.

Sometimes, 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 Bitvise SSH Server Advanced settings, separately for each group or account settings entry.

Connect rules

Connect rules control what destinations the SSH client will be able to connect to using client-2-server port forwarding. There are four types of connect rules: those that match IPv4 addresses, IPv4 addresses, DNS names, and a separate rule type that matches everything.

An IPv4 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, and is equivalent to a match-all rule.

IPv6 rules work similarly to IPv4 rules, except that there are up to 128 significant bits.

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, and is equivalent to a match-all rule.

Bitvise SSH Server processes Connect rules in the order they are configured. When the first match is found, the action configured for that rule is taken, and no further rules are searched.

If Bitvise SSH Server gets a client-to-server tunneling request for which there is no match in the account's Connect rules, the Connect rules of the corresponding 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. There is a separate list of listening rules for IPv4 and IPv6 requests.

A listen rule identifies an IP address of one of the server's network interfaces, and a port range for which the SSH client is allowed or denied listening. The special address 0.0.0.0 for IPv4, or "::" for IPv6, 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 Bitvise SSH Server gets a server-to-client tunneling request for which there is no match in the account's Listen rules, 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 SSH server resides on machine 10.10.10.5 in your internal network, and you wish to allow the user to connect, via SSH tunneling, 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 Bitvise SSH Server account settings entry for the user if one does not yet exist. Then, in Advanced settings, you would open the group or account settings entry that you wish to configure this restriction for, and perform the following:

  1. Add 'allow' rule for client-2-server connections:
    1. open the 'Connect rules' list and click Add
    2. under Address type, select IPv4
    3. under IPV4 Address, input the IP address of the server to which the user is allowed to connect - in our example, 10.10.10.16
    4. 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)
    5. under Port range rule, set 'Port from' to the RDP port (3389), and 'Port to' to the same value
    6. under Instructions, enable the 'Allow connect' setting, and leave the rest at defaults
    7. click OK to confirm and add the configured rule
  2. Add a 'deny' rule for other client-2-server connections:
    1. click Add in 'Connect rules'
    2. the default will be a rule that covers all connections. Disable the 'Allow connect' setting, and 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 port forwarding 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 the SSH server to listen, you would add appropriate Listen rules as in the Example 2 (below).

Example 2: Permit a server-to-client binding

Suppose your SSH 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 the SSH server 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 only 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 Bitvise SSH Server account settings entry for the user if one does not yet exist. Then, in Advanced settings, you would open the group or account settings entry that you wish to configure this restriction for, and perform the following:

  1. Add 'allow' listening rule for 10.10.10.5:
    1. open 'Listening rules: IPv4' and click Add
    2. under IPv4 Address, input the IP address of the interface - in our example, 10.10.10.5
    3. under Port range, 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
  2. 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.
  3. Add 'deny' rule for other listening interfaces:
    1. click Add in 'Listening rules: IPv4'
    2. the default will be a rule that covers all IPv4 listening interfaces and all ports. Disable the 'Allow connect' setting, and click OK to add the rule.
  4. Add a 'deny' rule for IPv6:
    1. click Add in 'Listening rules: IPv6'
    2. the default will be a rule that covers all IPv6 listening interfaces and all ports. Disable the 'Allow connect' setting, and click OK to add the rule. Since you're not using any IPv6 interfaces, this will be the only IPv6 Listening 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

Master/Slave Synchronization and Clusters

In Bitvise SSH Server versions 6.xx and higher, the SSH server can be run in master/slave mode, which facilitates its use in a cluster.

The scope of the master/slave feature is to automate synchronization of SSH server settings between SSH servers. It is intended for use in environments where administrators would like to apply settings changes on one server (the master), and have the changes automatically propagate to others (slaves). The master/slave feature does not interact with solutions for server monitoring or load balancing. If your deployment requires e.g. load balancing, you will need an external solution for that.

To cause some or all aspects of the SSH server's configuration to be automatically reproduced from a primary installation to one or more secondary installations, use the Site type feature in Bitvise SSH Server Control Panel to configure the primary installation as the master. Then, configure secondary installations to run as slaves, and retrieve configuration changes from the master.

A typical cluster installation may wish a secondary server to appear identical to a primary server to its users. To achieve this, a slave would reproduce all aspects of the SSH server's configuration: settings, host keys, and password cache. The aspects of SSH server configuration that will be copied from the master are configured in the Site Type dialog for each slave installation.

Configuring Master/Slave Synchronization

Master/slave synchronization is configured through the Site type setting in the Bitvise SSH Server Control Panel (top right corner of the Server tab). The following steps are required:
  1. On the master server:
    1. Set site type to Master, and configure a password which slave SSH servers will be required to present in order to synchronize settings from the master. We highly recommend configuring a long, secure, randomly generated password as described on this page.
    2. Use the Manage host keys interface to export the public keys of all host keys used by the SSH server. Alternately, write down the master's employed host key fingerprints so that you can enter them manually into slave configuration.
  2. On slave servers:
    1. Set site type to Slave.
    2. Import the master's host keys through the Host and fingerprints setting. Alternately, use Add Fp to add a master's host key fingerprint, without importing the key.
    3. Enter the master's network address and port, and set the synchronization password to match the one configured on the master.
    4. In the remaining slave settings, configure which aspects of SSH server settings to synchronize from the master. Host keys can be synchronized from the master only if this is permitted in master settings.
    5. If you enable Auto-manage trusted host keys, the slave server will automatically add to its "Host keys and fingerprints" setting any new host keys generated on the master, assuming they haven't yet been employed. If the host key is already employed when it is first seen by the slave, the slave will not be able to connect regardless of this setting, because it has no previous knowledge of the key.

Chapter 1.12

Scriptable configuration with BssCfg

Bitvise SSH Server comes with a textual configuration utility called 'BssCfg' which is useful for administering SSH servers 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. BssCfg also allows remote server administration from client machines where it is not possible to use Bitvise SSH Client and its Remote Control Panel feature.

Note: Everything that can be configured through BssCfg can also be configured through the graphical Bitvise SSH Server Control Panel, and vice versa. Users who don't need scriptable configuration do not need to learn BssCfg. Such users should simply use the graphical settings, accessed through the Bitvise SSH Server Control Panel.

Running BssCfg. The BssCfg utility resides in the SSH server 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 BssCfg is started with 'BssCfg settings importText -i'. This mode allows the user to inspect and manipulate Bitvise SSH Server 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 BssCfg like in a Windows command prompt.

Command types. In interactive mode, BssCfg supports two types of commands for interaction and management of settings:

Note that in non-interactive mode ('BssCfg settings importText' without the '-i' parameter), BssCfg 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 BssCfg utility. This example illustrates how BssCfg can be used to configure a command to be run automatically whenever a user logs into Bitvise SSH Server. 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 BssCfg 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 BssCfg 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").sfsMap.mountPoints.(sfsMountPath eqi "/").realRootPath "C:\\Temp\\SFTP"

This will set the "Real root path" setting for the default mount point of 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:

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 groups 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 help with the BssCfg utility, feel free to contact us. 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

COM-based programmatic configuration

Bitvise SSH Server comes with a COM DLL which can be used to configure SSH server 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 configuration COM object can be used for the same purposes as the BssCfg utility and the Bitvise SSH Server 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 SSH server's installation directory in the file BssCfgManip.idl.

BssCfgManip COM object name

The exact name of the BssCfgManip COM object is changed in SSH server versions that contain changes to the configuration format. To find the name of the COM object for your installation, check the file BssCfgManip.idl in the Bitvise SSH Server installation directory.

For example, if your SSH server version is 6.02, the name of the object would be "BssCfg601.BssCfg601". This is because, even though your version is 6.02, the configuration format was last changed in version 6.01.

Virtual filesystem providers

Bitvise SSH Server 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 the SSH server's default provider, FlowSfsWin, 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 32-bit DLLs with a plain C interface. No licensing or royalty fees are required. Feel free to contact us to receive the header files needed.

SSH Server Control Panel protocol

Third party programs can interact with Bitvise SSH Server using the same protocol used by the SSH Server Control Panel, and can obtain the same information from the SSH Server that the SSH Server Control Panel displays. Look for BssStat.exe and BssStat.cpp in your SSH Server installation directory for an example command line program that implements the protocol, and its full source code.

Chapter 1.14

Interpreting SSH Server Log Files using Microsoft Log Parser

Bitvise SSH Server's textual log files are recorded in a machine processable XML format. It is straightforward to process XML files using any .NET language, but another way to extract information from Bitvise SSH Server log files is using Microsoft Log Parser.

When using Microsoft Log Parser, it is important to use the following parameters:

-fNames:XPath -fMode:Tree

With the -fNames:XPath parameter, field names will appear unambiguously, using the full XPath of the attribute to which they refer. The default setting, "compact", can assign unpredictable field names to attributes used in different types of log entries.

Example 1

A basic command to find out who and when logged onto the server:

LogParser -i:XML -fNames:XPath -fMode:Tree "SELECT /log/event/@time, /log/event/session/@windowsAccount, /log/event/session/@virtualAccount FROM *.log WHERE /log/event/@name = 'I_LOGON_AUTH_SUCCEEDED'"

A optimization of the above command - we can shorten the paths using the -rootXPath parameter:

LogParser -i:XML -fNames:XPath -fMode:Tree -rootXPath:/log/event "SELECT /event/@time, /event/session/@windowsAccount, /event/session/@virtualAccount FROM *.log WHERE /event/@name = 'I_LOGON_AUTH_SUCCEEDED'"

We can use aliases to clarify output headers:

LogParser -i:XML -fNames:XPath -fMode:Tree -rootXPath:/log/event "SELECT /event/@time AS Time, /event/session/@windowsAccount AS WinAccount, /event/session/@virtualAccount AS VirtAccount FROM *.log WHERE /event/@name = 'I_LOGON_AUTH_SUCCEEDED'"

Show only logons to Windows accounts:

LogParser -i:XML -fNames:XPath -fMode:Tree -rootXPath:/log/event "SELECT /event/@time AS Time, /event/session/@windowsAccount AS WinAccount, FROM *.log WHERE /event/@name = 'I_LOGON_AUTH_SUCCEEDED' AND /event/session/@virtualAccount IS NULL"

Show only logons to virtual accounts - using the VirtAccount alias in WHERE clause to shorten the command:

LogParser -i:XML -fNames:XPath -fMode:Tree -rootXPath:/log/event "SELECT /event/@time AS Time, /event/session/@virtualAccount AS VirtAccount FROM *.log WHERE /event/@name = 'I_LOGON_AUTH_SUCCEEDED' AND VirtAccount IS NOT NULL"

Show all Windows and virtual logons on August 7, 2014 (local time):

LogParser -i:XML -fNames:XPath -fMode:Tree -rootXPath:/log/event "SELECT /event/@time AS Time, /event/session/@windowsAccount AS WinAccount, /event/session/@virtualAccount AS VirtAccount FROM *.log WHERE /event/@name = 'I_LOGON_AUTH_SUCCEEDED' AND Time BETWEEN '2014-08-07' AND '2014-08-08'"

Example 2

Enumerate the times and remote addresses of logins for a virtual user named "Michele". This is not yet ideal - the matching in this example is case-sensitive:

LogParser -i:XML -fNames:XPath -fMode:Tree -rootXPath:/log/event "SELECT /event/@time AS Time, /event/session/@remoteAddress AS RemoteAddress FROM *.log WHERE /event/@name = 'I_LOGON_AUTH_SUCCEEDED' AND /event/session/@virtualAccount = 'Michele'"

An improvement on the above matches the username in case-insensitive fashion:

LogParser -i:XML -fNames:XPath -fMode:Tree -rootXPath:/log/event "SELECT /event/@time AS Time, /event/session/@remoteAddress AS RemoteAddress FROM *.log WHERE /event/@name = 'I_LOGON_AUTH_SUCCEEDED' AND /event/session/@virtualAccount LIKE 'Michele'"

To enumerate the times and remote addresses of all virtual users whose name starts with "M", case insensitive:

LogParser -i:XML -fNames:XPath -fMode:Tree -rootXPath:/log/event "SELECT /event/@time AS Time, /event/session/@remoteAddress AS RemoteAddress, /event/session/@virtualAccount AS VirtAccount FROM *.log WHERE /event/@name = 'I_LOGON_AUTH_SUCCEEDED' AND VirtAccount LIKE 'M%'"

Example 3

To find out who and when transferred which files:

LogParser -i:XML -fNames:XPath -fMode:Tree -rootXPath:/log/event "SELECT /event/@time AS Time, /event/session/@windowsAccount AS WinAccount, /event/session/@virtualAccount AS VirtAccount, /event/sfs/parameters/@path AS Path, /event/sfs/parameters/@bytesWritten AS BytesWritten, /event/sfs/parameters/@bytesRead AS BytesRead FROM *.log WHERE /event/@name = 'I_SFS_TRANSFER_FILE'"

Limit the above query to files that have only been written to:

LogParser -i:XML -fNames:XPath -fMode:Tree -rootXPath:/log/event "SELECT /event/@time AS Time, /event/session/@windowsAccount AS WinAccount, /event/session/@virtualAccount AS VirtAccount, /event/sfs/parameters/@path AS Path, /event/sfs/parameters/@bytesWritten AS BytesWritten, /event/sfs/parameters/@bytesRead AS BytesRead FROM *.log WHERE /event/@name = 'I_SFS_TRANSFER_FILE' AND BytesWritten <> 0"

Find out who removed which '*.docx' or '*.doc' files (case-insensitive) on August 7, 2014, between 2 pm and 7:30 pm (local time):

LogParser -i:XML -fNames:XPath -fMode:Tree -rootXPath:/log/event "SELECT /event/session/@windowsAccount AS WinAccount, /event/session/@virtualAccount AS VirtAccount, /event/sfs/parameters/@path AS Path FROM *.log WHERE /event/@name = 'I_SFS_REMOVE_FILE' AND /event/@time BETWEEN '2014-08-07 14:00' AND '2014-08-07 19:30' AND (Path LIKE '%.docx' OR Path LIKE '%.doc')"

More Information

For more information on the Log Parser's SQL SELECT statement, execute:

LogParser -h GRAMMAR

We also suggest checking out the -o:DATAGRID output format.

Chapter 1.15

Useful resources and utilities

Log analysis. Sideview has developed Splunk for WinSSHD - an application based on Splunk which provides a reporting interface for log data generated by WinSSHD. Users can generate list reports and detail views, and navigate inside charts and tables to see more reports and more details. (At the time of Bitvise SSH Server 5.50 release, this program is only known known to be compatible with the WinSSHD log format used in versions up to 5.26.)

Command-line utilities. The following is a list of command-line utilities which will likely be useful to Bitvise SSH Server 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.

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

Resources:

Part 2. Tutorials

Chapter 2.1

Frequently Asked Questions about Bitvise SSH Server

As an administrator of Bitvise SSH Server, you should first become comfortable with the SSH server's log files. Bitvise SSH Server 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 SSH server installation directory.

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

Personal Edition

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

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

Note that Bitvise SSH Server may be installed in the Personal Edition only by genuine, non-commercial personal users who are not using the SSH server 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 Bitvise SSH Server Personal Edition on a domain controller?

The 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 Bitvise SSH Server 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.

Q02. What are the limitations of the Personal Edition?

The Bitvise SSH Server Personal Edition:

If you are trying to make a decision about whether to use the Personal or Standard Edition, please note that in most cases, this is not a technical decision. All organizations, as well as personal users who do not qualify as non-commercial, must purchase a license for the Standard Edition. The Personal Edition is available only for users who are both personal and non-commercial, and are therefore likely to be unaffected by the above limitations.

Configuring and Running

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

For a basic, open setup, just start Bitvise SSH Server 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 the SSH server for remote administration, the default server settings do not need to be changed. The one exception is the "Open Windows Firewall Setting", described in Q10B.

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. See the page Securing Bitvise SSH Server for more information.

Q10B. I can connect to Bitvise SSH Server from the local network, but not from the internet.

To help prevent inadvertently exposing your SSH server to the internet before it has been properly configured, Bitvise SSH Server will not open its ports to the internet by default. When you are ready to open your server to internet connections, go to Easy SSH server settings, and change the setting "Open Windows Firewall" to "Open port(s) to any computer". If your Windows Firewall is disabled, or if you prefer to manage it manually, change this setting to "Do not change Windows Firewall settings".

If you still cannot connect from the internet after making this change, make sure that your router is properly configured to forward SSH connections to the SSH server. You can configure the router directly through its administrative interface, or if the router can be managed using Universal Plug and Play, you can set Bitvise SSH Server to configure it. To let the SSH server manage the router, enable "Automatically configure router (requires UPnP)" in Easy SSH server settings.

Q10C. A client is able to establish a TCP connection to Bitvise SSH Server, but the session hangs before proceeding to user authentication; or else, the SSH connection fails at a later point, due to an error such as "data integrity failure". What could be causing this behavior?

Ensure that the MTU network setting (Maximal Transmission Unit) is set correctly on all devices involved in the TCP connection between the client and the server. Default MTU settings will work in most cases, but some ways of connecting to the internet require a lower MTU setting. In these cases, an MTU setting that's too large will result in segments of data being cut off, resulting in an inability of the client and the server to establish or maintain an SSH session.

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 Advanced settings is provided for this purpose. Configure an entry specifying the domain name where you would like Bitvise SSH Server to start looking up unqualified usernames. You can configure multiple such domain names.

Q12. What client software can I use to connect to Bitvise SSH Server?

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 Bitvise SSH Client for most purposes. Our SSH client 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 Bitvise SSH Server logs show an error like 'Failed to bind listening socket', and I cannot connect to the server.

Such an error indicates that another application is already listening on the port you have configured for Bitvise SSH Server. 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 Bitvise SSH Server 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.

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

Q15. I'm trying to get some SSH client to work with Bitvise SSH Server. However, the session gets terminated immediately after connecting, and the SSH server logs tell 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, Bitvise SSH Server 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 the SSH server starts impersonating that user, the server loses permission to execute the necessary child processes. In order to use Bitvise SSH Server, you must configure your machine so that the remote user will be able to run executables in the SSH server 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.

Q16. I'm trying to use PowerShell in a terminal session using the 'dumb' terminal type. It doesn't display a command prompt.

From Windows PowerShell Cookbook:

When PowerShell detects that its input or output streams have been redirected, it suppresses any prompts that it might normally display. If you want to host an interactive PowerShell prompt inside another application (such as Emacs), use "-" as the argument for the -File parameter. In many shells, this implies "taken from standard input."

powershell -File -

Thanks to Jim Snyder for discovering this solution.

Q17. An SSH client hangs for no apparent reason when connecting to Bitvise SSH Server, and then the session breaks due to an authentication timeout.

If the SSH client is set up to try Kerberos authentication, but Kerberos isn't configured properly between the client and the server, the client might hang when it tries to unsuccessfully figure out how to use Kerberos to authenticate with the server.

To rectify this behavior, you can disable GSSAPI (Kerberos) either in the SSH client, or in the SSH server.

To disable GSSAPI authentication in Bitvise SSH server, find the settings Kerberos 5 authentication and NTLM authentication on the Access control page of Advanced settings, and set them both to Disabled. Disabling both methods will disable GSSAPI authentication for all users. The server won't advertise the GSSAPI algorithms, and the client won't shoot itself in the foot trying to figure out how to authenticate using Kerberos.

Q18. How do I set up Bitvise SSH Server to use a different terminal shell, such as Windows PowerShell, or a Unix-style shell such as Bash?

The default terminal shell used by Bitvise SSH Server is the Windows Command Interpreter, cmd.exe, which is available on all Windows platforms. You can configure a different terminal shell in Advanced SSH Server settings, either individually for a particular user in their account settings entry, or for a group of users in their group settings entry. The two settings you must configure are as follows:

To use a terminal shell that doesn't come with Windows, such as Bash, you will need to install it. You can obtain Bash from a variety of sources, such as Cygwin.

For Windows PowerShell, see also Question 16.

File Transfer

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

If using Easy settings, you will need to use the "Virtual filesystem layout" setting under a Windows or virtual account settings entry. Configure this setting to "Limit to root directory", and then configure the Root directory. Alternately, select "Advanced filesystem layout", and you can configure multiple directories.

If using Advanced settings, this feature is configurable either per-account or per-group. 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.

Note that the virtual filesystem limits will affect only users who log in through SFTP or SCP. Users who are allowed terminal shell access, and who access your SSH server this way, will still be able to see the entire filesystem that they are allowed to see based on their Windows filesystem permissions.

If you want users to only have file transfer access, you should prevent them from using a terminal shell. See also Securing Bitvise SSH Server.

Q22. What is the difference between SCP and SFTP?

SCP and SFTP are different file transfer protocols. SFTP, despite its name, has no relation to FTP. It is a remote file access protocol which provides rich and fine-grained functionality for managing, accessing, and modifying files on an SSH server. SCP is an adaptation of the Unix utility 'rcp' to run over an SSH session, and provides simplistic file transfer operations only. SFTP is launched by the client opening a session channel and requesting the 'sftp' subsystem. SCP is launched by the client instructing the server to execute the SCP program via an SSH exec request.

In WinSSHD 4, the SCP subsystem was not supported as well as SFTP. Since Bitvise SSH Server 5, support for the two subsystems is integrated, and the same virtual filesystem can be accessed through SFTP or SCP.

Q23. How do I get WinSCP to work with Bitvise SSH Server?

All recent WinSCP versions work fine in SFTP mode. Very old WinSCP versions that only supported SCP can also be made to work if you install the Cygwin bash shell and Cygwin's SCP, and configure the bash shell to be used in the SSH server. However, it is much easier to simply use a recent version of WinSCP, and toggle the setting to make it talk SFTP.

Q24. The SFTP client I tested performs poorly with Bitvise SSH Server. How can I improve performance?

The answer to this question depends on whether you are seeing the server consume 100% CPU during most of the transfer.

If the server is consuming 100% CPU, then you are running into hardware limitations of the server system.

If you are not seeing 100% CPU consumption during most of the transfer, you're running into a limitation of the client. For high-performance transfers, the SFTP client must implement performance optimizations appropriate to available bandwidth and latency. These optimizations include:

The only performance parameter the SFTP server has control over is its own SSH channel receive window size. However, this only affects the speed of uploads - not downloads - and Bitvise SSH Server is already aggressive in this regard; it's unlikely to bottleneck the client.

If your SFTP client doesn't reach transfer speeds that would cause the server to reach 100% CPU consumption, but network bandwidth is still available, try with a different client. Our Bitvise SSH Client performs aggressive pipelining, which might perform better than some other clients.

Please do not try to improve performance by disabling encryption. The performance impact of encryption is minimal, and disabling it defeats the principal goal of SSH, which is security.

Q25. How do I configure Bitvise SSH Server so that clients can upload files, but not see or modify existing files - a file drop scenario?

This behavior can be configured in Advanced SSH server settings. Under the account or group settings entry for which you want to configure this, open mount point settings under "Virtual filesystem". To implement a file drop scenario, remove permissions to List, Read Existing, Write Existing, and Delete Existing, but enable the permission to Read/Write/Delete New. Also, enable "Show empty directory if no access" (enabled by default).

For more general information, see also Configuring Bitvise SSH Server for SFTP, SCP file transfer.

Q26. I don't want the SSH Server to load the users' Windows profiles during file transfer sessions. How do I prevent the Windows profile from being loaded?

Bitvise SSH Server will load the user's Windows profile if it's asked to provide functionality that requires the Windows profile. To avoid loading the Windows profile, turn off options which require it to be loaded. In Advanced SSH server settings, either in a user or group settings entry, disable the following options:

With all of the above options disabled, the SSH Server will not load the user's Windows profile for file transfer sessions.

Q27. Does Bitvise SSH Server lock files being accessed by a client, to prevent them being accessed by other applications? How do we enable such blocking?

By default, files that clients are accessing via SFTP or SCP will be available for access by other processes. However, some SFTP clients that implement a sufficiently high SFTP version can request different locking.

For most clients that do not implement this, the administrator of the SSH Server can configure settings for a mount point so that files are locked by default. This is done in Advanced SSH server settings, under Virtual filesystem layout settings for the mount point in question, under Provider settings. The parameter that needs to be added is FileShare, with value Disable.

Public Key Authentication

If you are having problems related to public key authentication, you may also want to check our page about Public Keys in SSH.

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

In the Bitvise SSH Server Control Panel, open Advanced 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.

Screenshots for importing a client authentication public key:

Please also read this page in the Bitvise SSH Server Users' Guide for important information about how SSH server account and group settings work.

Q31. I am unable to import a user's public key into Bitvise SSH Server's 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 a private key instead of the public key, or it may be an SSH1 public key file instead of an SSH2 key. The formats supported by Bitvise SSH Server 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.

Another possible reason you might have trouble importing a public key is if you try to import it into the SSH server's "Manage host keys" interface, instead of into an SSH account settings entry. The SSH server's host key management interface, which is accessible directly from the Bitvise SSH Server Control Panel, is intended to manage host keys that are used to authenticate the SSH server. The place to import a client authentication keypair is into an individual account settings entry, either in Easy or Advanced SSH server settings.

Q32. The client sent their public key, I imported it into SSH Server settings, but public key authentication doesn't work, and they're still being prompted for a password. Help!

Most likely, the user's client software is doing one or more of the following:

To see which problem it is, check the Activity tab of the SSH Server Control Panel, and/or the SSH Server's textual log files. If the client is not attempting to use public key authentication, you will see this as an absence of any public key authentication messages in the logs. If the client is using a different key, log messages will show that the server does not recognize the key they're using. If the client is attempting to log into a different account, there will be discrepancies between the user name provided by the client, and the one for which the public key has been imported in SSH Server settings.

Q33. How do I set up public key authentication with Bitvise SSH Client?

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

Q34. When I use password authentication, I can access EFS-encrypted files, and network shares on the server's Local Area Network. But when I use public key authentication, EFS-encrypted files and network shares are inaccessible. How can I access them when using public key authentication?

In order to access EFS-encrypted files, the server needs to provide Windows with your password. Similarly, to provide you with access to network shares on other computers in the server's network, the server needs to authenticate you with the computer providing the network share.

When you log in using password authentication, the SSH server conveys your password to Windows, and your login session is created in a way which allows Windows to access EFS-encrypted files, and pass your login credentials to other Windows computers in the network, providing you with access to network shares.

When you log in using public key authentication, Bitvise SSH Server versions 5.50 and higher are able to create your login session without the SSH server knowing your account password. However, a login session created this way does not have credentials necessary to access EFS-encrypted files and network shares.

One way to solve this is to add your Windows account's password to the SSH server's password cache. You can do this through the "Manage password cache" link on the "Server" tab of the Bitvise SSH Server Control Panel. The server will remember the password you enter indefinitely. When you log in using public key authentication, the server will use the cached password to create a logon session which will have credentials necessary to access network shares. This will work as long as the cached password remains synchronized with the account's actual password.

If you only need access to network shares (but not EFS-encrypted files), another way is to configure the SSH server, through per-group or per-account settings, to explicitly establish connections to one or more network shares, by providing network share access credentials in the SSH server's configuration. This can be done through the "Windows file shares" section of an account or group settings entry, in Advanced SSH server settings.

Q35. How can I let users manage their public keys themselves, without administrative intervention?

Bitvise SSH Server supports two ways for users to manage their client authentication public keys without requiring the administrator's manual intervention.

SSH clients that support the Secure Shell Public Key Subsystem (RFC 4819) can use this functionality to add or remove public keys associated with their account in Bitvise SSH Server settings. This feature is enabled for all accounts by default.

Windows accounts that have write access to their Windows profile directory can use the authorized_keys synchronization mechanism. To enable this, the administrator must enable the setting Synchronize with authorized_keys under Access control in Advanced SSH server settings. Windows users can then store a file named "authorized_keys" in a subdirectory named ".ssh" under their Windows profile directory. When the user's SSH session ends, Bitvise SSH Server will check for the presence of this file, and if it exists, the public keys encoded in this file will replace the public keys configured for the user in SSH server settings. This feature is disabled by default because some users have existing .ssh/authorized_keys files they are not aware of, which would conflict with intended SSH server settings.

Q36. When I examine the SSH server's log entries for a session, I see a logon attempt using the "none" method that fails, followed by a logon attempt using the "publickey" method that fails, followed by public key authentication that succeeds. How can I resolve the two failures?

These failures are a normal part of SSH authentication. First, the client may send a "none" authentication request, which is intended to fail, but provides the client with information about authentication methods supported by the server. Then, the client may attempt public key authentication without a signature, which is also intended to fail, but tells the client whether the server will accept the client's public key. Then, armed with this knowledge, the client sends the actual public key authentication request, which succeeds.

The client could avoid the preliminary requests if it were to assume outright that the server supports public key authentication, and that the server will accept the public key the client is trying to use. In this case, the client can just send the full public key request directly, as its first authentication request.

However, it is perfectly okay for the client to send the preliminary requests. This is a normal part of SSH authentication.

Account Settings

Q40. How do Bitvise SSH Server account settings work?

Please read this page in the Bitvise SSH Server 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 Bitvise SSH Server settings. In settings for the individual account or group, open Virtual filesystem layout > Mount points, and set the 'Real root path' setting for the default mount point ('/') to the directory you want them to access.

Usage Issues and Operation Concerns

Q51. How can a user change their password remotely?

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

Additionally, Bitvise SSH Server 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 SSH server 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.

Recent Bitvise SSH Server versions also allow virtual account users to change their passwords using an SSH client that supports this feature, such as Bitvise SSH Client. Virtual account passwords can also be changed by an administrator in Bitvise SSH Server settings or using bsscfg.

Q52. My Bitvise SSH Server log is showing multiple login attempts from an unknown IP address. The log shows the server is accepting these connections and the client is trying to guess a username and password. Your software is letting hackers into my PC!

In order to refuse access to unauthorized users, while still allowing authorized users to log in, the SSH server must accept connection attempts coming from permitted sources, and must allow those connections to reach a point where the client can provide authentication credentials.

When installed with default settings, Bitvise SSH Server will already take several steps to thwart unauthorized attackers.

One way is by imposing a delay between login attempts. The default delay is 3 seconds. Without any other countermeasures, this 3 second delay would ensure that even an account with a weak password, e.g. 6 letters chosen randomly from an alphabet of 26, would on average take years of back-to-back attempts to guess. (Note however that passwords that short are still very weak and are not recommended.)

Another way Bitvise SSH Server tries to thwart attackers is through automatic blocking of IP addresses that have recently initiated multiple failed login attempts. In default settings, the SSH server will block for 1 hour any IP address that initiates more than 20 failed login attempts in 5 minutes.

If you wish to see fewer password guessing attempts, an effective mitigation is to configure your SSH server to accept connections on a port other than 22. This would not be very effective against a determined attacker, but will avoid random hackers looking for low-hanging fruit. Any random port number between 1024 and 65535 is suitable. The only issue is that any legitimate client that tries to connect to your server will then need to be configured with the port number in addition to the host name.

Despite these countermeasures, it is very important to make sure that your accounts are configured with complex passwords, and to lock down your settings so as not to grant access that you don't need to. For more information and for password complexity guidelines, see Securing Bitvise SSH Server.

Q53. When I install Bitvise SSH Server, it creates a local Windows account named BvSsh_VirtualUsers (or similar). What is the purpose of this account?

When you configure virtual users in Bitvise SSH Server settings, the SSH server needs to provide some kind of security context for actions taken by those users when they connect. Advanced SSH server settings allow you to configure a specific Windows account that should be used as security context for virtual users. If you don't take explicit steps to configure this, the SSH server will use as security context a default local Windows account, which it creates and manages for this purpose. In a default (unnamed) SSH server installation, this account is named BvSsh_VirtualUsers. (If your first installation was a version prior to 5.50, the account is named WinSSHD_VirtualUsers.)

You can use Windows Explorer, and other Windows administration tools, to apply Windows filesystem permissions to the BvSsh_VirtualUsers account. In this way, you can control what parts of your system a virtual user will be able to access. These Windows security permissions will apply to virtual users even if they are permitted to use terminal shell or exec requests, in which case, the virtual filesystem configured in SSH server settings does not apply.

You should not attempt to delete the BvSsh_VirtualUsers account, or change its password. Such changes will either be detrimental to your SSH server's operation, and/or will not be effective. Bitvise SSH Server will automatically enable this account when the SSH server is started, and disable it when the server is stopped. The SSH server will also periodically reset the password to this account, and set it to an extremely long, extremely complex random value. It will not be possible to log into this account, other than by allowing the SSH server to use it as security context for a virtual account.

Q54. Bitvise SSH Server's log files are very detailed. How do I extract just the information I'm looking for?

The SSH Server's log files are intended to be machine processable. Log files use the XML format, which can be handled by utilities such as Microsoft Log Parser, or custom applications. It's straightforward to process XML files using any .NET language.

For more information, see also Interpreting SSH Server log files using Microsoft Log Parser.

Q55. I enabled the "Omit server version" setting, but the server still sends the name of the product in the SSH version string. How can I completely remove product information from the version string sent to clients?

We support removing the exact server version number from the SSH version string, but we do not support completely removing the product name.

Any hacker who can exploit a server-specific vulnerability can also identify the server product based on the contents of the KEXINIT packet the server sends. KEXINIT packets are sent in plaintext and have specific patterns which are sufficient not just to identify the make of the server, but also a particular version subset.

Removing the server product name from the version string only serves to deny this information to legitimate clients, where it can be useful.

Upgrading and Moving

Q60. How do I upgrade my Bitvise SSH Server to the latest version?

There are two parts to the upgrade process:

  1. Ensure that you have a license with upgrade access for the SSH server version to which you are upgrading. You can verify your upgrade access expiry date by logging into your License Overview.

    If your upgrade access has expired, you will be able to add the desired number of license-years through the "Place a New Order" section under the license information. The expected new upgrade expiry date will be displayed on the page when you enter the desired number of license-years. The full cost will be displayed on the next page, at checkout.

  2. When you have a license with an activation code suitable for the latest version, download the installer for the latest version from our website. Run the installer on the computer where you want to upgrade your SSH server installation, and follow the process. Apply the new activation code in the Bitvise SSH Server Control Panel, once the upgrade is complete.

Q61. Will my settings and keys be preserved when I upgrade?

In general, yes. The upgrade process is intended to preserve your keypairs, your password cache, and your settings.

We do recommend making a backup of your settings before you upgrade. Settings can be exported using the Export function in the Bitvise SSH Server or WinSSHD Control Panel. A settings backup may be useful if the new version encounters a problem reading your settings, or if you decide to downgrade to the previous version again. The older version may not be able to read your settings once the new version has upgraded them.

Q62. I would like to move my SSH server to a different computer. How do I move my settings, password cache, and keypairs?

Settings. To move Bitvise SSH Server or WinSSHD settings, use the Export feature from the SSH server's Control Panel. On the new Bitvise SSH Server installation, use the Import feature to import the settings. Moving the settings will also move any client authentication public keys configured for user authentication.

Password Cache. In the latest Bitvise SSH Server versions, the password cache is necessary only if you use Windows domain accounts that need to log in using public key authentication, and also need to have implicit access as that account to network resources on other computers on the local network. In the latest Bitvise SSH Server versions, the password cache can be backed up into, and restored from a file, using Bitvise SSH Server Control Panel > Manage password cache > More > Backup items to file. If you want to move the password cache, but are using an older SSH server version which does not support backing up the password cache, you may want to upgrade the existing installation to a version that supports this, before moving.

Host Keypairs. It only makes sense to move keypairs used for SSH server authentication if the SSH clients accessing the server will continue to access the server using the same port, IP address, and/or DNS name. If there will be any change in what address or port the SSH client uses to access the SSH server, the client will need to re-verify the server's host key, so there's no benefit to transferring keypairs to the new installation.

If the clients will continue to access the server at the same address, the host authentication keypairs can be moved through the SSH Server Control Panel > Manage host keys.

Older WinSSHD versions (e.g. versions 4.xx) do not contain a user interface function to export a host authentication keypair. Depending on the version, you may be able to use the "wcfg" command line configuration utility to export the keypair. Alternately, you could upgrade to a more recent version in place, and export the keypair using the new version.

Client Public Keys. Public keys configured for client authentication are part of SSH server settings, and are moved implicitly when you export and import settings.

Contacting Support

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

Contact us through our Contact page, and describe your problem in as detailed manner as possible. The more information you provide, the greater the chance of a swift and effective resolution.

Chapter 2.2

Configuring Bitvise SSH Server for SFTP, SCP file transfer

Bitvise SSH Server provides multiple types of secure remote access to Windows. A frequent usage scenario is to configure the SSH server specifically for file transfer, without exposing the machine to terminal shell, tunneling and other types of access. This tutorial explains step-by-step how to configure Bitvise SSH Server for a primary role as a file transfer server using SFTP and SCP.

  1. Install Bitvise SSH Server. Do not start it yet.

  2. When you install Bitvise SSH Server, the Easy settings wizard should appear. You can also access Easy settings at any later time by clicking Open easy settings.

    If you have already performed any changes to SSH server settings, click 'Restore', and then 'Reset settings to default values'.

  3. The first tab of Easy settings is named Server settings. When you are ready for your server to accept connections over the internet, you will need to open this tab and enable the checkbox 'Automatically configure router (requires UPnP)'. You will also need to change the setting 'Open Windows Firewall' to 'Open port(s) to any computer'.

    We recommend that you wait with the router and firewall settings until you have configured the server, and have tested your configuration by connecting to the server with an SSH or SFTP client installed on the same computer, or in your local network.

  4. The next tab of Easy settings is named Windows accounts. This tutorial describes how to configure Bitvise SSH Server for file transfer using virtual accounts. Therefore, disable the checkbox 'Allow login to any Windows account'. This will prevent anyone from logging into your SSH server using accounts not configured in SSH server settings.

    To use Bitvise SSH Server with virtual accounts only, do not add any Windows account entries under 'Windows accounts'.

  5. The final tab of Easy settings is named Virtual accounts. Click the 'Add' button to add a virtual account, or use the 'Edit' button to edit an existing virtual account. Edit the virtual account settings as follows:

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

    • Login allowed. Enable this if the account should be able to connect to your server. You can disable this to prevent access without deleting the account.

    • Allow file transfer. Enable this checkbox to allow SFTP and SCP access.

    • Allow terminal. Disable this checkbox to prevent the user from accessing the Windows command interpreter and other programs over SSH.

    • Allow port forwarding. Disable this checkbox to prevent the user from accessing other network services over SSH.

    • Virtual filesystem layout. Set this to either 'Limit to root directory', or to 'Advanced filesystem layout'.

      When using 'Limit to root directory', you can set up the user so they are able to access only a single directory and its subdirectories over SFTP. When using 'Advanced filesystem layout', you can configure multiple directories that the user can access through virtual filesystem mount points.

      To guarantee that your users can access the directories you configure for them, make sure that the Windows account BvSsh_VirtualUsers has Windows filesystem permissions to access those directories. This account is a member of the Users group, so if the Users group has sufficient access, the virtual account will have access as well.

  6. When you are done configuring virtual users, click 'Save changes' to exit Easy settings. You can now start Bitvise SSH Server and try connecting with an SCP or SFTP client. We also recommend trying to connect with an SSH terminal client to ensure that users cannot access terminal shell and port forwarding.
  7. Once you have tested your configuration and ensured that it works correctly, click 'Open easy settings' again and edit the router and firewall settings on the 'Server settings' tab to open your server to internet connections.

Having configured Bitvise SSH Server in this way, it will only accept connections from users who know one of the Virtual account usernames and passwords you have defined. The SSH server 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 root directory, or to their virtual filesystem mount points.

If you installed Bitvise SSH Server on a domain controller, the above steps will not be sufficient. Domain controllers do not have local accounts, so the SSH server cannot manage a local account to provide the security context for virtual users. In this case, you will need to use the SSH server's Advanced settings and configure a domain account to provide security context. Consult Configuring groups and accounts to learn more about how Bitvise SSH Server operates, so that you can configure it properly.

Chapter 2.3

Securing Bitvise SSH Server

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

Securing Bitvise SSH Server involves:

  1. Identifying which of the above features you want to limit or disable, and doing so.

  2. Configuring the SSH server to allow access only to a restricted subset of Windows accounts configured on the system, or only to virtual accounts configured in Bitvise SSH Server itself.

  3. 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 SSH server settings prematurely. Make sure that you can establish a connection first. Make sure that you and your users can use the SSH 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 Bitvise SSH Client on the same machine where Bitvise SSH Server is installed, and use that client to connect to the SSH server to test the connection. After you are satisfied that the features you require work correctly, start securing SSH server 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 Bitvise SSH Server 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 for an overview of how Bitvise SSH Server treats Windows- and virtual accounts and groups.

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

Open this group and disable the following settings:

If you are using Bitvise SSH Server for more than only file transfer, you may want to leave some of these features enabled. In particular, if you are using SSH for tunneling, do not disable port forwarding. If you are using SSH 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 Bitvise SSH Server Advanced 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 an SSH server account settings entry under Windows accounts, and configure the following fields:

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, Bitvise SSH Server 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 SSH server 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. Bitvise SSH Server 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 in via SSH.

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 server to use public-key authentication. For more information, consult the public key section of the Bitvise SSH Server Usage FAQ.

Chapter 2.4

Public keys in SSH

This page attempts to explain public keys, as used in SSH, to readers unfamiliar with the concept.

The following concepts need to be understood by everyone, including beginner users:

SSH sessions use public keys for two main purposes: server authentication, and client authentication. Both processes work very similarly, but they involve separate sets of keys. When discussing a specific public key in the context of SSH, it is important to be aware whether the key is intended to authenticate the server, or a client.

In Bitvise SSH Server

In Bitvise SSH Server:

If you are trying to configure public key authentication for a client connecting to Bitvise SSH Server, check also the Public Key Authentication section of our Bitvise SSH Server Usage FAQ.

In Bitvise SSH Client

In Bitvise SSH Client:

Chapter 2.5

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:

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:

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

Web browsing over SSH

It is possible to configure most browsers to use a SOCKS proxy for outgoing HTTP connections. This makes it possible to forward web browser traffic over an encrypted SSH connection.

The recommended browser for this purpose is Firefox, because it can be configured to resolve DNS names through the SOCKS proxy, so the names of the websites you're browsing don't leak out through DNS queries.

You will need an account at an SSH server which allows you to use port forwarding. Configure Bitvise SSH Client to connect to that SSH server, and enable the SOCKS proxy feature under the Services tab.

In Firefox, configure Bitvise SSH Client as the SOCKS proxy in Tools > Options > Advanced > Network > Connection > Settings. Use Manual proxy configuration, enter 127.0.0.1 under SOCKS proxy, and port 1080. (This is assuming you left SOCKS proxy settings in the SSH client at their defaults.)

Open a blank Firefox tab and navigate to "about:config". Find the setting:

network.proxy.socks_remote_dns

Set this setting to true.

You are now done. Firefox will connect to websites through Bitvise SSH Client's SOCKS proxy feature, and your web traffic will be tunneled over the encrypted SSH connection between your SSH client and the SSH server.

Note that the part of the traffic between the SSH server and the web server(s) will remain unencrypted. By using SSH tunneling, you are shielding your web traffic from prying eyes in your local network or at your local Internet Service Provider. However, the plaintext of your web sessions will now be available to the SSH server administrator, as well as to the ISP through which the SSH server connects to your destination web servers.

Chapter 2.7

X11 forwarding with Bitvise SSH Client

The X11 forwarding feature in Bitvise SSH Client provides one way for an SSH connection to access graphical applications running on the SSH server. X11 forwarding is an alternative to forwarding a Remote Desktop or VNC connection. It differs from Remote Desktop or VNC in that remote application windows appear seamlessly in the client's desktop, without forwarding a complete desktop. X11 forwarding is best used with Unix-style servers running applications intended to run under X11. For connections to Windows servers, Remote Desktop is the native option.

Installing an X11 server

In order to use X11 forwarding, an X11 server needs to be installed on the client. One such server is available as part of Cygwin.

To install the Cygwin X11 server without installing the entire (and large) Cygwin platform, perform the following steps in the Cygwin installer:

  1. Proceed to the Select Packages page. On this page, you should see a package tree with All - Default as the root.
  2. To prevent installing packages selected by default, cycle All - Default by clicking on the Default part until it is set to All - Uninstall. (screenshot)
  3. Find the package All / X11 / xorg-server: X.Org X servers and select it by changing Skip at the beginning of the line to the current stable version - that is, the first version after Skip. (screenshot)
  4. Proceed to the next page and complete the installation.

Starting the Cygwin X11 server

You can start the Cygwin X11 server by executing:

C:\cygwin\bin\XWin -multiwindow

If the X11 server starts successfully, a new X-resembling icon will appear in the task bar notification area (the system tray). To close the X11 server, right click on the icon and select Exit from the right-click menu.

If the X11 server fails to launch, an error message will be displayed. A common failure reason is that an X11 server is already running. It is possible to run multiple X11 servers on the same computer, but each will need to be associated with a unique display number. For example, to start the X11 server on display 3, you would execute:

C:\cygwin\bin\XWin :3 -multiwindow

Note: We do not recommend opening the firewall for the X11 server (the XWin.exe process).

Setting up Bitvise SSH Client

In the SSH client's Terminal tab, enable X11 forwarding. If your X11 server runs on a non-default display (a display other than 0), the setting X11 Forwarding - Display will need to be changed, as well. For example, if your X11 server runs on display 3, change the setting to: 127.0.0.1:3.0.

Use the Login button to establish an SSH connection. Open a terminal console, and in it, run an X11 program (e.g. xemacs). The program should appear in a new window on your screen.

Chapter 2.8

Single-Click Remote Desktop Forwarding

Since Tunnelier (Bitvise SSH Client) 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 Bitvise SSH Client 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 Bitvise SSH Server, must be installed. On the client machine, an SSH client, such as Bitvise SSH Client, 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.

  1. Install Bitvise SSH Server on the server (the machine you wish to access with Remote Desktop).
  2. No changes to the default Bitvise SSH Server configuration are required to use Remote Desktop over SSH. You may wish to make changes to the default SSH server configuration later on, to restrict what SSH features are accessible to remote users. However, for the time being, keep your SSH server settings at default until your Remote Desktop over SSH is up and running.
  3. Apart from installing Bitvise SSH Server, 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.
  4. Start the Bitvise SSH Server from the Bitvise SSH Server Control Panel.
  5. Install Bitvise SSH Client on the machine from which you wish to access the server.
  6. Configure the following settings on the Login tab in Bitvise SSH Client. 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 Bitvise SSH Server is listening on. If you have made no changes to the default SSH server 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 the SSH client has been restarted.
  7. In the C2S Forwarding tab in Bitvise SSH Client, 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 the SSH client 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.
  8. Click the Login button in Bitvise SSH Client 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.
  9. 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'.
  10. 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.
  11. Click Connect. The SSH session 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.
  12. You can make sure that your Remote Desktop connection is going through SSH by checking the Bitvise SSH Client 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, the SSH client 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 Bitvise SSH Client log area, as well as in the log entries recorded by the SSH server. Especially in the case of an authentication failure, the SSH server log entries will contain important diagnostic information.

Please see our contact and support page for more information and links to documents about how to go about resolving problems with Bitvise SSH Client and Server.

Chapter 2.9

Securing Windows File Shares with SSH Port Forwarding

This article is not about SFTP or SCP file transfer. The topic is Windows file shares: folders exposed to a local network using built-in Windows functionality.

It is possible to set up SSH port forwarding so as to access Windows file shares from a remote Windows computer over SSH. This allows accessing remote files over an encrypted connection as if they were files on a local drive, without requiring SFTP or SCP file transfers.

Recent Windows Versions

In recent versions of Windows, including Vista, Windows 7, and 2008, setting up port forwarding of file shares over SSH is now considerably more difficult. If you are not an advanced Windows user, we recommend adapting your approach so that you can use SFTP or SCP for file transfer instead.

If you would still like to port forward Windows file shares, this can be done using an approach described by Jan Just Keijser in this tutorial. Jan's tutorial was written with PuTTY in mind, but the crucial steps will work identically with Bitvise SSH Client.

Note: Following this tutorial will cause SMB to run much later after booting the computer. This may cause problems if your computer is joined to the domain, because Group Policy is distributed via SMB from the domain controller. Other boot-time tasks such as virus scanner updates also sometimes use SMB, and may fail.

In the event that Jan's tutorial becomes unavailable, the following is a summary:

You can now use UNC paths of the form \\10.255.255.1\sharename\ to access file shares on the destination server.

Older Windows Platforms

On Windows versions prior to Windows Vista, you can forward file shares over an SSH connection by forwarding 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:

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)

  1. Install Bitvise SSH Server on the server - the machine that has the resources you wish to access with Windows file sharing.
  2. No changes to the default SSH Server configuration are required to use Windows file sharing over SSH. You may wish to make changes to the default SSH Server configuration later on, to restrict what SSH features are accessible to remote users. However, for the time being, keep your SSH Server settings at default until your file sharing over SSH is up and running.
  3. Apart from installing the SSH Server, 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 Bitvise SSH Client and Server. 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.
  4. Start the SSH server from the Bitvise SSH Server Control Panel.

On the client machine:

  1. 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.
  2. Install Bitvise SSH Client on the client (the machine from which you wish to be accessing the server machine's shared resources).
  3. Configure the following settings on the Login tab of the SSH Client. 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 the SSH Server is listening on. If you have made no changes to the default SSH Server 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 the SSH Client has been restarted.
  4. In the C2S Forwarding tab of Bitvise SSH Client, 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.
  5. Click the Login button in Bitvise SSH Client and observe the log area for any errors. If the session is established without errors, the SSH setup is running.
  6. 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.
  7. 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 C2S rule listening interface in the SSH Client (above).
  8. 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 SSH connection remains established.
  9. You can make sure that your file sharing connections are going through Bitvise SSH Client by checking the SSH Client 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, the SSH Client should output a log message stating 'Closing client-to-server forwarding channel from ... to ...:139'.

Troubleshooting

If you encounter problems establishing the SSH session, you will receive diagnostic information in the SSH Client log area, as well as in the log entries recorded by SSH Server on the server side. Especially in the case of an authentication failure, the SSH Server log entries will contain important diagnostic information. Inspect the SSH Server 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 Bitvise SSH Client and Server.

Chapter 2.9.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:

  1. 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.
  2. 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.9.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:

  1. 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.
  2. 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.9.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:

  1. Open Start, Settings, Control Panel, Network.
  2. Switch to the Adapters tab, then click 'Add...'
  3. Leave the default '802.3' Frame Type and click OK. (802.3 is CSMA/CD - ETHERNET.)
  4. A 'Windows NT Setup' dialog will pop up saying that the Windows NT4 CD is required. Insert the CD and click Continue.
  5. Once back in Network properties, switch to the Bindings tab.
  6. Change 'Show bindings for:' to 'all adapters'.
  7. Open the newly created adapter tree (should contain names as '[N] Loopback Adapter', where N is the order number).
  8. Disable everything except 'TCP/IP Protocol' in the subtree.
  9. Switch to the Protocols tab.
  10. A 'Network Settings Change' dialog pops up. Click Yes to save changes.
  11. The 'Microsoft TCP/IP Properties' dialog opens. Change 'Adapter:' to the newly created adapter (should be '[N] MS Loopback Adapter').
  12. 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).
  13. Click OK to close 'Microsoft TCP/IP Properties'.
  14. Click Close to close Network.
  15. 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.10

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 Bitvise SSH Client and Server, 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:

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

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

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:

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.

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 are 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 reliability 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:

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:

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.

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.

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.