Environment Variable Expansion

A number of string fields in Bitvise SSH Server's account and group settings entries support environment variable expansion. To see if a particular field supports this, check the help text associated with that field in Advanced SSH Server settings.

The basic rule of environment variable expansion is that if there is an environment variable named VAR, containing the value "value", then any occurrence of "%VAR%" will be replaced with "value":

C:\Dir\File-%VAR%.txt -> C:\Dir\File-value.txt

The SSH Server also supports advanced expansion rules. These mirror the expansion functionality available in the Windows Command Prompt:

%VAR:~N% Uses a substring of the value of VAR, starting from zero-based offset N.
%VAR:~N,L% Uses a substring of the value of VAR, of length L, starting from zero-based offset N.
%VAR:S1=S2% Before using the value of VAR, replaces each occurrence of S1 within the value with S2.
%VAR:*S1=S2% Before using the value of VAR, replaces with S2 all characters from the beginning of the value and until the end of the first occurrence of S1.
%=LOWER:VAR% Converts the value to lowercase. This can be combined with other advanced expansion rules. When combined, conversion to lowercase will be done first. For example: if USERNAME has value "JOHN", then %=LOWER:USERNAME:j=J% will produce "John". Requires SSH Server 6.41 or higher.
%=UPPER:VAR% Like =LOWER, but converts to uppercase. Requires SSH Server 6.41 or higher.

For example, a home directory structure such as M:\Home\a\Aaron, M:\Home\b\Benjamin, can be configured on a group-wide basis, without requiring account-specific settings entries, by setting the group home directory to:

M:\Home\%USERNAME:0,1%\%USERNAME%

On-upload command

When using environment variables in an On-upload command, we recommend that the script is given no parameters on the command line, but that it instead obtains information from its environment block. For example, in PowerShell:

$env:SSHUPLOADFILE

This is to avoid pitfalls when parsing the command line, which may contain a path under the SSH client's control.

Supported Variables

When environment variable expansion is performed in the context of a logged-on user's session, any variable in the user's environment block can be used.

When environment variable expansion is performed for on-logon, on-logoff, on-upload commands configured to execute in service context, any variable in the server's environment block can be used.

In addition, the SSH Server will define the following variables:

BVSSHSERVERINSTANCE The name of the SSH Server instance chosen during installation. On servers with multiple SSH Server instances, can be used to distinguish which instance the user is currently logged into. Added in version 8.15.
HOME If not already set by Windows, set by the SSH Server to a concatenation of HOMEDRIVE and HOMEPATH. The SSH Server does not set this for commands executed in service context.
HOMEDRIVE If not already set by Windows, set by the SSH Server to the drive part of what the SSH Server thinks is the user's home path. It is possible for this home path to change as the session progresses. The SSH Server does not set this for commands executed in service context.
HOMEPATH If not already set by Windows, set by the SSH Server to the directory path part of what the SSH Server thinks is the user's home path. It is possible for this home path to change as the session progresses. The SSH Server does not set this for commands executed in service context.
SSH_CLIENT The SSH client's IP address, followed by space, followed by port number. The SSH Server does set this for commands executed in service context.
SSH_CONNECTION The SSH client's IP address, followed by space, followed by the local interface address at which the SSH Server accepted the client's connection. The SSH Server does set this for commands executed in service context.
SSHLOGEVENT Defined for Execute command tasks triggered by a log event. Contains JSON-encoded data for the event that triggered the command. This can be loaded in PowerShell using ConvertFrom-Json $env:SSHLOGEVENT. Added in version 9.12.
SSHSESSIONID The numerical session ID assigned to the current client's session by the SSH Server. The first session receives ID 1001. The SSH Server does set this for commands executed in service context.
SSHUPLOADBYTES Defined during execution of an on-upload command. Contains the number of bytes written to the uploaded file by the client.
SSHUPLOADFILE Defined during execution of an on-upload command. Contains the full local drive and path to the file written to by the client. Warning: Part or all of this parameter is controlled by the SSH client, which can create file names using syntax not expected by the server administrator. If passing this environment variable to e.g. the Windows command interpreter, make sure to enclose it in double quotes: "%SSHUPLOADFILE%"
SSHUPLOADENDBY Has the value "CLIENT" if the file was closed by the client, or "CLEANUP" if it was closed by session teardown. Files with the value "CLEANUP" are likely to be incomplete. Added in version 7.12.
SSHUPLOADMOUNTPATH Defined during execution of an on-upload command. Contains the value of the Virtual mount path setting for the mount point into which the file was uploaded. Added in version 9.12.
SSHUPLOADNEW Defined during execution of an on-upload command. Contains 1 if a new file was created, 0 otherwise. Added in version 6.31.
SSHUPLOADRESIZE Defined during execution of an on-upload command. Contains 1 if at least one file resize request by the client was successfully completed, or if an existing file was truncated when opened. Contains 0 otherwise. Added in version 6.31.
SSHUPLOADROOTPATH Defined during execution of an on-upload command. Contains the value of the Real root path setting for the mount point into which the file was uploaded. Undefined if the mount point has no Real root path. Added in version 8.15.
SSHWINGROUP Defined if the logged-on user is a Windows account (not virtual). Set to the name of the Windows group settings entry from which the Windows account inherits settings. Set to "EVERYONE" if the account inherits settings from the Everyone group. The SSH Server does set this for commands executed in service context.
SSHWINGROUPDOMAIN Defined if the logged-on user is a Windows account (not virtual), and if the user inherits settings from a Windows domain group. Set to the domain name configured in the group settings entry. The SSH Server does set this for commands executed in service context.
SSHWINUSER Defined if the logged-on user is a Windows account (not virtual). Set to the account name portion (without domain) of the user's full account name. The SSH Server does set this for commands executed in service context.
SSHWINUSERDOMAIN Defined if the logged-on user is a Windows account (not virtual). Set to the domain name portion of the user's full account name, or the name of the local computer if the account is local. The SSH Server does set this for commands executed in service context.
USERDOMAIN If not already set by Windows, the SSH Server sets this to the domain name portion of the user's full account name, or the name of the local computer if the account is local. The SSH Server does not set this for commands executed in service context.
USERNAME If not already set by Windows, the SSH Server sets this to the account name portion (without domain) of the user's full account name. The SSH Server does not set this for commands executed in service context.
USERPN_DOMAINPART For Windows domain accounts, the domain part of USERPRINCIPALNAME. Added in version 9.26.
USERPN_USERPART For Windows domain accounts, the user part of USERPRINCIPALNAME. Added in version 9.26.
USERPRINCIPALNAME For Windows domain accounts, the value of the User-Principal-Name attribute associated with the currently logged-on user in the Active Directory. Added in version 8.15.
VIRTGROUP Defined if the logged-on user is a virtual account defined in SSH Server settings. Set to the name of the virtual group settings entry from which the virtual account inherits settings. The SSH Server does set this for commands executed in service context.
VIRTUSER Defined if the logged-on user is a virtual account defined in SSH Server settings. Set to the name of the virtual account. The SSH Server does set this for commands executed in service context.