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