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
- Configuring and Running
- File Transfer Issues
- Public Key Authentication
- Account Settings
- Usage Issues and Operation Concerns
- Upgrading and Moving
- Contacting Support
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:
- Can use only local Windows accounts (no domains).
- Can configure only one Windows group ('everyone').
- Can configure only one virtual group.
- Has a limit of 10 Windows account entries.
- Has a limit of 10 virtual account entries.
- GSSAPI authentication is disabled (Kerberos and NTLM).
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 'email@example.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.
- You are trying to log in with an account configured in Bitvise SSH Server to use the 'interactive' logon type, but this account does not have the Windows permission to log on locally. On domain controllers, this permission is not granted to regular users by default and must be enabled in the Domain Controller Security Policy.
- You have successfully logged in with an account configured in Bitvise SSH Server to use the 'network' logon type, or you logged in using GSSAPI (Kerberos or NTLM) authentication, but starting the terminal shell failed with an Access Denied error. This is because default filesystem permissions on Windows 2003 servers grant access to cmd.exe and other command line tools only to 'interactive' users. Switch this user or group in Bitvise SSH Server to use the 'interactive' logon type, or modify filesystem permissions for cmd.exe and other command-line tools to allow execution by users logged in with the 'network' logon type.
For more information, please read the Network vs. interactive logon section in the 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 a terminal session using the 'dumb' terminal type. It doesn't display a command prompt.
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.
File Transfer Issues
Q21. When users log in, they can see all drives on my server. How do I limit them to a certain directory?
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 limitations of our design. Our SSH architecture in version 5.xx is CPU intensive. It uses lots of fiber switching internally, which is intended to make for a more robust implementation, but it doesn't jibe well with systems that have smaller CPU caches.
Additionally, the SFTP subsystem is separated from the main SSH service. This is to reduce exposure and improve security, but it comes at a cost of more internal data passing between the subsystems.
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:
- Read/write request sizing.
- Read/write request pipelining.
- SSH channel receive window sizing.
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.
Public Key Authentication
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.
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 an SSH1 public key file instead of an SSH2 key, or it might be something entirely alien. 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.
Q32. I set up my account for public key authentication, but the next time I tried to log in, I still got asked for a password. Why?
This should no longer be a problem in Bitvise SSH Server versions 5.50 or higher. With previous versions, you had to configure a Windows account's password in the SSH server's password cache before it was possible to use public key authentication. Bitvise SSH Server 5.50 and newer no longer requires a password in the password cache.
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 network shares on the server's Local Area Network. But when I use public key authentication, these network shares are inaccessible. How can I access network shares when using public key authentication?
In order 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 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 network shares.
There are multiple ways to get access to network shares when you log on using public key authentication. One way 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.
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.
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 LogParser, or custom applications. It's straightforward to process XML files using any .NET language.
If you're using Microsoft LogParser, make sure to use the parameter "-fnames:xpath". This way, 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.
Upgrading and Moving
Q60. How do I upgrade my Bitvise SSH Server to the latest version?
There are two parts to the upgrade process:
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.
- 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.
Q. I read the entire FAQ, but it didn't help me solve my problem. What do I do?
Visit our discussion groups. Use the search function to see if your issue has been raised in the past. If not, feel free to post a support query in the appropriate forum, in which you describe your problem in as detailed manner as possible. The more information you supply, the greater the chance of a swift and effective resolution.