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:

HOMEIf 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.
HOMEDRIVEIf 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.
HOMEPATHIf 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_CLIENTThe 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_CONNECTIONThe 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.
SSHSESSIONIDThe 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.
SSHUPLOADBYTESDefined during execution of an on-upload command. Contains the number of bytes written to the uploaded file by the client.
SSHUPLOADFILEDefined 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%"
SSHUPLOADENDBYHas 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.
SSHUPLOADNEWDefined during execution of an on-upload command. Contains 1 if a new file was created, 0 otherwise. Added in version 6.31.
SSHUPLOADRESIZEDefined 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.
SSHWINGROUPDefined 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.
SSHWINUSERDefined 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.
SSHWINUSERDOMAINDefined 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.
USERDOMAINIf 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.
USERNAMEIf 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.
VIRTGROUPDefined 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.
VIRTUSERDefined 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.