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
- Public Key Authentication
- Account Settings
- Usage Issues and Operation Concerns
- Upgrading and Moving
- Contacting Support
Q000. 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.
Q010. How do I use Bitvise SSH Server Personal Edition on a domain controller?
The Personal Edition does not support domain accounts; only local Windows accounts, and virtual accounts backed by a local Windows account.
On domain controllers, local accounts are not available, so it is not possible to make meaningful use of the Personal Edition of the SSH Server. For this reason, the Personal Edition option is not offered during installation on a domain controller.
Q020. 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
Q100. 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 Q103.
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.
Q103. 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.
Q110. How do I log in to a Windows domain account?
It is best practice to specify the username in either the domain - backslash - account format; for example, "COMPANY\John"; or with a fully qualified name; for example, "firstname.lastname@example.org".
It is possible to log into a domain account by providing only the account name, e.g. "John". In this case, authentication outcome may be undependable if Windows finds multiple matches. For example, there may be a local account named "John", a domain account named "DOMAIN\John", and another one named "OTHER\John". You can control the outcome in such circumstances by configuring the Windows domain order setting in Advanced SSH Server settings.
Users can also log in using Unix realm accounts if they are in a trust relationship with the server's domain. Such users must always provide the fully qualified Unix realm account name, because Windows cannot look up Unix realm usernames.
Q120. 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.
Q130. 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.
Q140. 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.
Q150. 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.
Q160. I'm trying to use PowerShell in 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.
Q170. 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.
Q180. 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:
- Terminal shell: The command line to start your desired terminal shell interactively. For example:
PowerShell.exefor Windows PowerShell, or for Bash:
- Exec request prefix: The command line prefix to start a command with the shell non-interactively. For example:
PowerShell.exe -Command <SPACE>Note the space after "-Command" at the end! It needs to be there. Alternately, for Bash:
c:\path\to\bash.exe -c "Note the double quote mark at the end: that also needs to be there.
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 160.
Q185. How do I use the terminal shell or an exec request to run a process that should continue to run when the SSH session exits?
By default, all child processes of a terminal shell or exec request are terminated by the SSH Server automatically when the SSH session exits, unless you take extra steps to launch a process outside of the session's job object. You can do this using the following steps:
- Enable the setting Allow job breakaway in Advanced SSH Server settings. This setting can be configured either in an account settings entry for an individual account, or in a group settings entry as a default for a group of users.
- Within a terminal shell or exec request, use the BvRun utility in the SSH Server's installation directory using the -brj parameter to launch a child process outside of the session job.
Q190. I would like to provide a user with access only to port forwarding, but the client disconnects unless I also allow terminal shell access.
Most clients can be configured to not require a terminal shell when using port forwarding:
- If using OpenSSH, use the -T parameter ("Disable pseudo-tty allocation").
- If using plink (part of PuTTY), use the -N parameter ("don't start a shell/command").
- If using the graphical PuTTY client, enable Connection > SSH > Don't start a shell or command at all.
If using Bitvise SSH Client, the session won't be disconnected if a terminal window can't be opened, in the first place. However, if terminal shell and/or SFTP access are not available, you may want to disable the automatic opening of a terminal shell and/or SFTP window. This is configured under Options > On Login.
Q210. 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. 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 configuring mount points via Advanced settings for a specific account, note that the setting Inherit group mount points is enabled by default. Leaving this enabled will inherit a default mount point ("/") from group settings which allows full filesystem access unless it's redefined or undefined in the account settings entry.
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.
Q230. 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.
Q240. The SFTP client I tested performs poorly with Bitvise SSH Server. How can I improve performance?
The first thing to check is whether the server is consuming at least one CPU core at 100% during most of the transfer.
If the server is consuming 100% of at least one CPU core, then you are running into hardware limitations of the server system.
If you are not seeing 100% consumption of a CPU core during most of the transfer, you're running into a limitation of the client or network. 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% of a CPU core, 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 in most cases, and disabling it defeats the principal goal of SSH, which is security.
Q250. 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.
Q260. 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:
- Map remote home directory
- Map remembered shares
- Load profile for SCP and SFTP
With all of the above options disabled, the SSH Server will not load the user's Windows profile for file transfer sessions.
In the case of virtual accounts used for file transfer, the most common culprit that's causing the Windows profile to be loaded is that Load profile for SCP and SFTP is enabled in the virtual group settings entry. This is disabled in new SSH Server installations by default, but the setting is inherited when upgrading older configurations.
Q265. Should I disable Windows profile loading?
The latest versions of Bitvise SSH Server are configured by default to avoid profile loading for virtual accounts, but profiles are loaded for Windows accounts by default. This is okay as long as the Windows accounts are not accessed very frequently.
Several versions of Windows contain a leak which will lead to resource exhaustion after a very large number of profiles have been loaded, requiring the system to be restarted. Unfortunately, our exploration of this issue indicates that this is not a problem we can fix in the SSH Server. You can work around it by following instructions in Q260 to disable profile loading.
Loading a Windows profile can also take varying amounts of time; sometimes up to a minute with large domain account profiles. Disabling profile loading when not needed will improve performance.
Q270. 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.
Q280. How can I arrange an email notification to be sent when a file is uploaded via Bitvise SSH Server?
Bitvise SSH Server does not currently embed an email notification feature, but it can be configured to execute a command on successful upload, which you can use to send an email notification. You will be able to do so if you can use a third party program that will send an email message based on command line information.
An On-upload command can be configured in Advanced SSH Server settings, either in an account or group settings entry. This command will be executed every time a client uploads (writes to and closes) a file. The command supports environment variable expansion - you can use variables such as %SSHUPLOADFILE% and %SSHUPLOADBYTES% to pass information to a third party program that will e.g. send an email notification.
For more information about available variables, see Environment variable expansion.
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.
Q300. 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:
We recommend also the Accounts and groups section of the Bitvise SSH Server Users' Guide for additional important information.
Q310. 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.
Q320. 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:
- Not attempting to authenticate using a public key because the keypair is not properly configured in the client.
- Attempting to authenticate with a keypair that corresponds to a different public key than the one you imported for this client.
- Attempting to log into an account that does not match the one for which you imported this public key.
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.
Q330. How do I set up public key authentication with Bitvise SSH Client?
If you are able to connect to the SSH Server using password authentication, and if the SSH Server administrator has not prohibited users from managing their public keys, the simplest process is:
- Use the graphical Bitvise SSH Client to connect to the server.
- Once connected, open the Client key manager interface.
- Use Generate New to create a new keypair.
- Right click on the keypair and select Upload to server. You should now be able to authenticate using this keypair.
Alternately, if you must configure public key authentication before connecting to the server, or the server does not allow you to manage your public keys:
- Open the graphical Bitvise SSH Client. You do not need to connect to the server.
- Open the Client key manager interface.
- Use Generate New to create a new keypair.
- Use the Export button to export the public key in standard SSH2 format.
- Send the public key file to the server administrator. If you're the administrator, transfer it to the server machine.
- Follow instructions in Q300 (above) to import the public key into Bitvise SSH Server.
Once the public key has been uploaded or imported into the Server, 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, and copy the keypair into the profile using the Client key manager.
If you wish to manage public keys configured for your account on the Server non-interactively, or via the command line, you can also use spksc - a command line public key management client that's included with Bitvise SSH Client. In this case, run spksc from a Command Prompt for help.
Q340. 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.
Q350. 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.
Q360. 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.
Q370. Public key authentication for Windows accounts does not work unless I enter the account's password in the SSH Server's password cache. Even though Windows has been restarted, the SSH Server Control Panel continues to display the message "Public key authentication, as well as virtual accounts that use a custom security context, will not be fully operational until Windows is restarted."
It is possible that Windows has been configured to not load LSA authentication packages installed by third party programs. This prevents the loading of the SSH Server's authentication package, which it needs to create logon sessions where a password is not available.
To allow the SSH Server's authentication package to load, follow the instructions under "To disable LSA protection" as described in the Microsoft TechNet article Configuring Additional LSA Protection.
Q400. How do Bitvise SSH Server account settings work?
We recommend the Accounts and groups section of the Bitvise SSH Server Users' Guide for this important explanation.
Q430. 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.
Q440. How do I use virtual accounts on a domain controller?
On computers that are not domain controllers, Bitvise SSH Server manages a local Windows account to provide a security context for virtual account login sessions. See Q530 for more information about this account.
On domain controllers, the SSH Server cannot create this account because there is no concept of local accounts on a domain controller. If you would like to use virtual accounts on a domain controller, you need to create or designate a domain account which will provide a security context for your virtual account login sessions. You then need to configure this backing account in Advanced SSH Server settings, either individually for each virtual account settings entry, or in a group settings entry used by one or more virtual accounts.
Q445. How do I configure virtual accounts to use a domain account as security context?
If you would like your virtual accounts to use a domain account as their security context, open Advanced SSH server settings, and edit your Virtual group settings entries as follows:
- Change Security context to A specific Windows domain account.
- Configure the Windows account domain and Windows account name settings to identify the domain account.
Virtual account settings entries will inherit their security context settings from their assigned virtual group by default - unless settings for a specific virtual account are configured differently.
We recommend also adding the domain account's password to the SSH Server's password cache. See Q450.
Q450. If I use an explicitly configured backing account to provide a custom security context for virtual accounts, do I need to enter the backing account's password into the SSH Server's password cache?
When you explicitly configure a backing account for virtual users, you can choose to save the password for this backing account in the SSH Server's password cache using the Manage password cache interface in the SSH Server Control Panel.
If you configure the password cache, the SSH Server will be able to create virtual account login sessions that will have implicit access to EFS-encrypted files and network resources (e.g. Windows shares) accessible to the backing account. If you do not configure the password cache, the virtual account sessions will still work, but without access to such resources. See also Q340, which describes the same issue when using Windows accounts with public key authentication.
Usage Issues and Operation Concerns
Q510. 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.
Q515. I'm using PuTTY or plink, and it logs me into a different account than I intend when I connect from a computer in the same domain. Why does this happen, and what can I do about it?
When used in a domain, PuTTY will automatically try to log you in using Kerberos + GSSAPI by default, using the Windows domain account with which you are logged into the client computer. PuTTY will do this even if you specify a different username for authentication, and have no intention of using Kerberos to authenticate. PuTTY is expecting the SSH Server to refuse the login if there is a username mismatch, but the SSH Server expects that the client would not have tried to authenticate with Kerberos if it didn't mean to.
The solution for this is to disable GSSAPI authentication either in PuTTY, or in Bitvise SSH Server. In PuTTY, it can be disabled under Connection > SSH > Auth > GSSAPI. In Bitvise SSH Server, it can be disabled in Advanced SSH server settings > Access control. If you disable both Kerberos 5 authentication and NTLM authentication, PuTTY will not be able to login with GSSAPI. But also, no other client will be able to log in using Kerberos or NTLM.
Q520. I'm seeing pop-ups from Bitvise SSH Server showing unknown IP addresses trying to guess usernames and passwords. This worries me. What can I do about this?
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.
Q530. 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.
Q540. 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.
Q550. 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.
Q560. How do I import a list of IP addresses I want to block from a file?
You can do this using the SSH Server's scriptable configuration language. For example:
After adding entries, edit the rule list to make sure that their order is correct - for example, that individual IP address block rules appear in the list before a blanket allow-all rule.
Q570. How many simultaneous client connections does the SSH Server support?
The answer depends on the type of sessions, their activity, the lowest performance you find acceptable, and hardware resources available to the server.
At the time of this writing, the SSH Server comes configured by default to allow a maximum of 60 concurrent sessions with processes. This is configured with the settings Limit total sessions and Maximal total sessions, found in Advanced SSH Server settings, under Session.
Sessions with processes include file transfer sessions, terminal sessions, and exec requests. Sessions that do not run child processes include sessions that only use port forwarding, or SSH Server Remote Control, or the SSH public key subsystem. There is no pre-configured default limit for sessions without processes.
The number of simultaneous sessions with processes is limited by default for two reasons. One is that these sessions consume more resources per session. The other is that older Windows versions, including Windows Server 2003, which our SSH Server still supports, will run out of a kernel resource called desktop heap space if more sessions with processes are created.
In more recent versions of Windows, desktop heap space is not statically limited, so you can raise or remove the default setting that limits the number of sessions with processes. In this case, the SSH Server's ability to support a greater number of sessions will depend on the activity of the sessions, and your hardware resources. If most of the sessions have low activity, hundreds can be supported. However, if all sessions attempt to perform file transfer at maximum available speed, they will start competing much more quickly for CPU and bandwidth.
Given unlimited hardware resources, the SSH Server can support several hundred simultaneous sessions on a 32-bit platform, and several thousand on a 64-bit platform. However, you are likely to run into CPU or bandwidth limitations before that, and may want to restrict the maximum number of sessions to a number that works for you.
Q580. While testing in a domain environment, I find that when using the gssapi-with-mic authentication method, the SSH Client allows me to log into the SSH Server with no password. Is this secure?
Yes, this is secure. In order for this type of logon to work, all of the following has to be true:
- Both the client and server computers have to be part of a Windows domain. The client can also be in a Unix realm.
- The client and server must be either in the same Windows domain, or in separate domains or realms that have an established trust relationship.
- The user has to be logged into the client computer as a domain account that can also log into Windows on the server.
- Bitvise SSH Server has to be configured to allow login with this domain account.
- GSSAPI authentication (Kerberos and/or NTLM) has to be enabled in the SSH Server. Because it only works in strict conditions, it is enabled by default. It can be disabled in Advanced SSH Server settings, under Access control.
If all of the above conditions are met, then the user is already logged into Windows on the client machine with an account that has permissions to log into the SSH Server. In this circumstance, the Windows domain infrastructure allows the user to use the gssapi-with-mic authentication method to perform single-sign-on authentication into the server, without having to authenticate again. This is a security advantage: it allows the user's password to be more complex, because it does not have to be entered as often.
If you would like to prevent this, make a change to any of the conditions enumerated above. The most common situation where this could be a problem is if the SSH Server is configured to accept login from domain accounts that you do not in fact want to log in. In this case, configure the SSH Server more strictly to accept login only using accounts you approve of.
Q585. File transfers sometimes get interrupted with an error like "MAC error", "data integrity failure", or "integrity check failed". What is the cause?
This type of error can be caused by:
An incorrect MTU setting. The Maximal Transmission Unit setting might be set to a too high value at one of the computers or network components involved in the connection.
This is a likely cause if the error:
- occurs with multiple types of client software over the same link;
- occurs early in the session, e.g. soon after starting the first upload or download, or even during authentication.
Accidental corruption of data in transmission that is not detected at a lower network layer. The TCP/IP protocol will detect errors in transmission with a probability of 65535 out of 65536, leaving a 1 in 2^16 chance that a transmission error will not be detected. If you are transferring a large file using a wireless link, or another type of connection that is prone to transmission errors, then any errors not detected by TCP/IP will cause an integrity check failure at the SSH layer. In this case, it is best to either switch to a more reliable link, or to use a client that is able to reconnect and resume transfer.
This is a likely cause if the error:
- occurs with multiple types of client software over the same link;
- occurs on the order of once per gigabyte of data transferred (depends on transmission error rate).
Implementation problem. The client that's interacting with the SSH Server might have a bug where it occasionally writes over the data it's sending or receiving, resulting in this error.
This is a likely cause if the error occurs with a single type of client software, but not other client software over the same link.
Intentional data corruption by an attacker with access to the network connection. This is usually least likely, but is the kind of attack that SSH is designed to detect. If an attacker tampers with data in transit, the SSH protocol cannot continue the connection, but it can detect and report that tampering may have taken place.
This is a possible cause if prolonged investigation of other causes does not yield results.
Q590. I keep getting the error: "The Bitvise SSH Server settings file is currently locked by another process." How do I resolve this?
This message indicates that some process on the system is keeping SSH Server settings open. This could be e.g. a settings window left open in an idle Remote Desktop session; it could be a BssCfgManip script that's intended to modify settings automatically, that has hung for some reason with locked settings; it could be the settings interface is open by an administrator through an SSH Client via the SSH Server Remote Control Panel.
If you cannot identify the program that is locking the settings, the easiest way to resolve the issue would be to restart the system. This will interrupt any SSH connections or Remote Desktop sessions that could be keeping the settings locked.
If the problem persists after restart, the most likely explanation is that the settings are being locked by an automated process. However, in most cases, the settings are just open in another logon session.
Q595. Users are getting the error: "Logon was successful, but the server has encountered logging problems. Only administrators can connect at this point." How do I resolve this?
You need to resolve the logging issue.
This error means that the SSH Server is unable to log to its textual log files. In Advanced SSH Server settings, under Logging, there is a setting that controls how the server should react when this happens. The default option is Allow connections from administrators only, and this option is being activated if you're seeing this message.
As server administrator, you need to investigate what's going on with the textual log files. Does the configured textual log file directory exist? We recommend that this directory is on a local drive; if it's configured as a network share, this may not be available to the SSH Server reliably.
Is there space on the drive where the log directory is located? If the drive is out of space, this issue would occur.
Is logging set to a higher level than needed? If yes, this can fill up disk space. The log level we recommend for textual log files is Errors, Warnings, Info. We do not recommend logging Trace or Debug events unless you are trying to debug a specific problem.
Upgrading and Moving
Q600. 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.
Q610. 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.
Q620. 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 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.