salt-vm-tools

The VMTools salt integration script installs, removes, or checks the status of a Salt minion (salt-minion) in a VMware controlled Virtual Machine environment.

This script operates as a BASH script in Linux environments and a PowerShell script in Windows environments.

The Salt minion is a Onedir architecture based Python 3 Salt minion leveraging relenv (https://github.com/saltstack/relenv) onedir option internally. The Salt minion is fully self-contained and requires no additional dependencies.

The script can install, remove, and check the status of an installed Salt minion either using a direct command line option or via VMware's use of Guest Variables, commonly referred to as guestVars.

In every two-step installation example, you would be well-served to verify against the SHA256 sum of the downloaded svtminion.sh file.

_sha256sums:

The SHA256 sum of the svtminion.sh file, per release, is:

• 2026.10.07: 9729545299104fc376f5839e600a3cc4e23346ce597b7700888938e3deef5f8b
• 2026.09.03: 17d0c77d804270bade1989c239ce9883f67cf24a2b655a438b4e6c6cd74f4be3
• 2026.07.23: 0b004fafdaa147ee5af9d53a931d0e90ca1d72e1676dc5186ecab6897381529b
• 2026.05.08: c10353160af24cfb90ffba896268cf320d8e0dd568fb590dd0b8f4e16f17eabb
• 2026.05.01: 24ccc901292f4074b8a498800410d5c9baadf1b6f8ba93e24a869c7229bde356
• 2026.03.13: 736e80955a47e67f897880c45e62d29281b5c17c5bef90ea5632922fd724583e
• 2026.01.09: d4dc2379866122f50fc68944be669454070c2e97457532eb0acffc7d9fa80ddb
• 2026.01.08: 6bef866af8315befd99763a7782fe1552a98605c5e59429f26ce37963f7a53c1
• 2025.12.12: ec17529cb407d7797a8810edaf4aed74005d8c1961da90a2728099b4657cd645
• 2025.12.10: 964e2bf9b810c613a7aacd4052ad12d3c20f1d3504df70d85c4e278429cbe4a9
• 2025.12.09: 7d8ac0ef090e8e90f4f4d0071a6cd6ec44dd258a835d3946125c9f400b059940
• 2025.12.08: 03ea7103a0021f8b8508be315ad10492cbceab353823567bd41b3a3609b21e04
• 2024.12.05: dc6c2438d94a535067c871f8d84960ddbf4b77f204f6d9e91fd3baa021b93270
• 2024.12.04: e7f4d7b242bd495c63e7b3240631411fbe65ac966ff2c1ef93399ceda9b5719f

If you're looking for a one-liner to install Salt Minion, please read below.

The latest versions of the svtminion scripts for Linux and Windows from the following https://github.com/saltstack/salt-vmtools/releases/latest/download/svtminion.sh and https://github.com/saltstack/salt-vmtools/releases/latest/download/svtminion.ps1

There are also .sha256 files for verifying against in the repo for the main branch. You can also get the correct sha256 sum for the tagged release from https://github.com/saltstack/salt-vmtools/releases/latest/download/svtminion.sh.sha256 and https://github.com/saltstack/salt-vmtools/releases/latest/download/svtminion.ps1.sha256

Configuration options

You can pass configuration to this script in 3 ways: guestVars, tools.conf and the command line. Each option has an order of precedence. The lowest being guestVars, followed by tools.conf, with the highest precedence being the command line. Each option is explained in the following sections.

guestVars (lowest preference)

VMware guestVars can contain the action this script performs as well as the minion config options to be set by this script. These have the lowest preference. Any config options defined in tools.conf or on the command line with the same name will override the values here.

The guestVars paths are as follows:

Option	guestVars Location
Action	vmware.components.salt_minion
Config	vmware.components.salt_minion.args

If set, the Action option will return a single word that is the action this script will perform. If set, the Config option will return a space delimited list of minion config options. For example: master=198.51.100.1 id=my_minion multiprocessing=false

These values are set on the host OS using the vmrun binary. For example:

# To set the Action to install the salt-minion
vmrun writeVariable "<path/to/vmx/file>" guestVar vmware.components.salt_minion "present"

# To set the Action to remove the salt-minion
vmrun writeVariable "<path/to/vmx/file>" guestVar vmware.components.salt_minion "absent"

# To set the Config Options
vmrun writeVariable "<path/to/vmx/file>" guestVar vmware.components.salt_minion.args "master=203.0.113.1"

They can be read on the guest OS using the vmtoolsd binary. For example:

# To read the Config Options
[root@fedora]# vmtoolsd --cmd "info-get guestinfo.vmware.components.salt_minion.args"
master=203.0.113.1

tools.conf (medium preference)

The tools.conf file contains the configurations for vmtools in an .ini format. This tool looks for the salt_minion section and uses the configurations defined under that section. This file is stored at:

OS	Location
Linux	/etc/vmware-tools/tools.conf
Windows	C:\ProgramData\VMware\VMware Tools\tools.conf

Below is an example of the salt_minion section as it may be defined in tools.conf:

[salt_minion]
master=203.0.113.1
conf_file=/etc/salt/minion
id=dev_minion

Note: Only minion config options and the script options are available in tools.conf. The desired script action cannot be obtained from tools.conf.

tools.conf is read the same way on Linux and Windows. White space around a line, the key, and the value is ignored, so master = 203.0.113.1 is the same as master=203.0.113.1. Lines that start with #, ; or , are comments. Windows (CRLF) line endings are fine.

Command Line (highest preference)

Any input passed to the script on the command line will take precedence over:

• The action and config options set in guestVars
• Anything configured in tools.conf with the same name.

Linux example:

[root@fedora]# svtminion.sh --install master=198.51.100.1

Windows example (note the single dash):

# Powershell
PS> svtminion.ps1 -install master=198.51.100.1

# cmd
C:\>powershell -file svtminion.ps1 -install master=198.51.100.1

Note: Higher preference configuration options will supersede lower preference values. For example, in the configuration preference examples outlined above, the final value for master is 198.51.100.1. Command line option for master overrides the tools.conf value of 203.0.113.1 and the guestVars value of 203.0.113.1 because the command line arguments have the highest precedence.

Note:* On Windows, if the minion ID is not passed, the guest host name will be used. However, on Linux there is no guarantee that a host name will be set. Therefore, a minion ID is automatically generated for the Salt minion. In either case, the minion ID can be specified in any of the 3 config options. For example:

id=myminion

Note: At all times preference is given to actions presented on the command line over those available from guestVars.

For example, if the following is passed on the command line:

[root@fedora]# svtminion.sh --install

And the following is defined in guestVars:

[root@fedora]# vmtoolsd --cmd "info-get guestinfo.vmware.components.salt_minion"
remove

Preference is given to the command line argument and the Salt minion package will be installed.

Script options

Three options control this script itself rather than the minion. They are set with key=value in the same places as the minion config options (guestVars args, tools.conf, and the command line), and are the equivalent of the command line switches shown:

Key	Equivalent switch	Applies to
source	--source / -Source	install
minionversion	--minionversion / -MinionVersion	install
loglevel	--loglevel / -LogLevel	every action

For example, to install from a location in an air-gapped environment, set the guestVars config to:

vmrun writeVariable "<path/to/vmx/file>" guestVar vmware.components.salt_minion.args "source=https://mirror.example.com/onedir minionversion=3007.1 master=203.0.113.1"

The same can be set in tools.conf:

[salt_minion]
master=203.0.113.1
source=https://mirror.example.com/onedir

Or on the command line:

[root@fedora]# svtminion.sh --install source=https://mirror.example.com/onedir

PS> svtminion.ps1 -Install source=https://mirror.example.com/onedir

These options behave the same on Linux and Windows:

• The order of preference is the same as the minion config options: command line, then tools.conf, then guestVars. A switch, for example --source, has the highest preference of all.
• The keys source, minionversion and loglevel are not case sensitive. The case of every other key is preserved. Values cannot contain spaces. The value is everything after the first =, so a URL can contain =.
• These three keys are never written to the minion config. Every other key=value option is still written to it. Salt's own log_level setting is a different option from loglevel, so it is still written to the minion config.
• source and minionversion only apply when installing (including --upgrade/-Upgrade). They are ignored for other actions. loglevel applies to every action.
• They are validated the same as the switches. An invalid value stops the script with exit code 126, whatever the log level, including silent.
• They cannot set the action. The action comes from the command line or the vmware.components.salt_minion guestVar.
• Tokens that are not key=value, have an empty key or value, or contain control characters are ignored with a warning. Tokens are not expanded in any way, * is just a *.
• A switch inside the guestVars value, for example --source <location>, is not supported. It is ignored with a warning. Use source=<location>.
• Command line key=value options end at the next switch (a token that starts with -).

Note: Some versions of VMware Tools add the guestVars args value to the command line when they run this script. Those values then have command line preference, and tools.conf cannot override them.

Logging

This script creates a log file at the following location:

OS	Location
Linux	/var/log
Windows	C:\Windows\temp

The content of the log file depends on the LogLevel passed on the command line. The default value is warning. Valid options are:

Log Level	Description
silent	Suppresses displayed output but logs errors and warnings
error	Displays and logs only errors
warning	Displays and logs errors and warnings
info	Displays and logs errors, warnings, and info messages
debug	Displays and logs all messages

The names of Log files are based on the action that the script is performing. The action can be defined on the command line or by setting a value in guestVars. Any logging that is unrelated to an action uses the keyword default. Valid actions are as follows:

• clear
• depend
• install
• reconfig
• remove
• start
• status
• stop

For example, running the script without a defined action results in a log file with the following name:

# Linux
bash>svtminion.sh --version --loglevel debug

/etc/log/vmware-svtminion.sh-default-YYYYMMDDhhmmss.log

# Windows
PS>.\svtminion.ps1 -LogLevel debug

or

cmd>powershell -file .\svtminion.ps1 -LogLevel debug

C:\Windows\temp\vmware-svtminion-default-YYYYMMDDhhmmss.log

Only the 10 most recent log files for each action are maintained. Excess log files are removed. Log files are not removed when the salt-minion service is uninstalled.

Linux Environment:

On Linux systems, the install script is a bash script with the following pre-requisites:

• systemctl
• curl
• sha512sum
• vmtoolsd
• grep
• awk
• sed
• cut
• wget
• find

svtminion.sh --help shows the command line options

Usage for the script svtminion.sh

    usage: ./svtminion.sh  [-c|--clear] [-d|--depend] [-h|--help] [-i|--install]
                 [-j|--source] [-l|--loglevel] [-m|--minionversion]
                 [-n|--reconfig] [-q|--stop] [-p|--start]
                 [-r|--remove] [-s|--status] [-u|--upgrade]
                 [-v|--version]

      -c, --clear     clear previous minion identifer and keys,
                         and set specified identifer if present
      -d, --depend    check dependencies required to run this script exist
      -h, --help      this message
      -i, --install   install and activate the salt-minion
                         parameters key=value can also be passed on the CLI
      -j, --source   specify location to install Salt Minion from
                         default is repo.saltproject.io location
                     for example: url location
                         http://my_web_server.com/my_salt_onedir
                         https://my_web_server.com/my_salt_onedir
                         file://my_path/my_salt_onedir
                        //my_path/my_salt_onedir
                     if specific version of Salt Minion specified, -m
                     then its appended to source, default[latest]
      -l, --loglevel  set log level for logging, silent error warning debug info
                         default loglevel is warning
      -m, --minionversion salt-minion version to install, default[latest]
      -n, --reconfig    salt-minion restarts after re-reading updated configuration
      -q, --stop      stop salt-minion
      -p, --start     start salt-minion (effectively restart salt-minion)
      -r, --remove    deactivate and remove the salt-minion
      -s, --status    return status for this script
      -u, --upgrade   upgrade when installing, used with --install
      -v, --version   version of this script

      The following can also be set using key=value, with no spaces,
      for example: source=https://my_web_server.com/my_salt_onedir
          source          same as --source, used when installing
          minionversion   same as --minionversion, used when installing
          loglevel        same as --loglevel
      key=value is read from the command line (after --install or
      --reconfig), tools.conf section [salt_minion] and the guest
      variable guestinfo./vmware.components.salt_minion.args
      Precedence, highest first: switch (for example --source),
          key=value on the command line, tools.conf, guest variables
      The keys source, minionversion and loglevel are not case
      sensitive and are not written to the minion configuration (all
      other key=value options are). An invalid value exits with code 126
      Note: when VMTools adds the guest variable args to the command
      line they have command line precedence over tools.conf

      salt-minion vmtools integration script
          example: ./svtminion.sh --status

Note: on Linux, the script does not support use of hostname as in file:///path1/path2

Windows Environment:

On Windows systems, the install script is a powershell script. The only prerequisite for Windows is the vmtoolsd.exe binary, which is used to query guestVars data. You can get help for this script by running svtminion.ps1 -h or Get-Help svtminion.ps1:

NAME
    .\svtminion.ps1

SYNOPSIS
    VMware Tools script for managing the Salt minion on a Windows guest.

SYNTAX
    .\svtminion.ps1 [-Install] [-Upgrade] [-MinionVersion <String>] [-Source <String>]
    [[-ConfigOptions] <String[]>] [-LogLevel <String>] [-Stop] [-Start] [-Help] [-Version] [<CommonParameters>]

    .\svtminion.ps1 [-Reconfig] [[-ConfigOptions] <String[]>] [-LogLevel <String>]
    [-Stop] [-Start] [-Help] [-Version] [<CommonParameters>]

    .\svtminion.ps1 [-Remove] [-LogLevel <String>] [-Stop] [-Start] [-Help] [-Version]
    [<CommonParameters>]

    .\svtminion.ps1 [-Clear] [-LogLevel <String>] [-Stop] [-Start] [-Help] [-Version]
    [<CommonParameters>]

    .\svtminion.ps1 [-Status] [-LogLevel <String>] [-Stop] [-Start] [-Help] [-Version]
    [<CommonParameters>]

    .\svtminion.ps1 [-Depend] [-LogLevel <String>] [-Stop] [-Start] [-Help] [-Version]
    [<CommonParameters>]

DESCRIPTION
    This script provides comprehensive management of the Salt minion on a Windows
    guest. The minion is a OneDir build available at:

    https://packages.broadcom.com/artifactory/saltproject-generic/onedir

    With this script, you can install, remove, check dependencies, retrieve
    installation status, and reset the Salt minion configuration.

    When run without parameters, the script checks for an action in `guestVars`. If
    no action is found, it exits with a `scriptFailed` (126) code.

    If an action is passed via the CLI or found in `guestVars`, the script gathers
    minion configuration options (e.g., `master=198.51.100.1`) from `guestVars`.
    Additional configuration options are obtained from `tools.conf`, which overrides
    any conflicting options from `guestVars`. CLI options take the highest
    precedence, followed by `tools.conf`, and finally `guestVars`.

    The following can also be set using key=value, with no spaces, in `guestVars`,
    `tools.conf` or on the CLI. They are the equivalent of the parameters shown:
    - source=<location> - the `-Source` parameter, used when installing
    - minionversion=<version> - the `-MinionVersion` parameter, used when installing
    - loglevel=<level> - the `-LogLevel` parameter
    For example: `source=https://my.domain.com/vmtools/salt minionversion=3006.8`.
    Their precedence is the same as the minion configuration options. An explicit
    parameter, for example `-Source`, takes precedence over all of them. These
    three keys are not case sensitive and are never written to the minion
    configuration (all other key=value options are). An invalid value exits with
    the `scriptFailed` (126) code. `source` and `minionversion` are ignored when
    not installing. They can not set the action.
    Note that Salt's own `log_level` setting is different, it is a minion
    configuration option and is written to the minion configuration. When VMware
    Tools adds the `guestVars` args to the CLI, those values have CLI precedence and
    `tools.conf` can not override them.

    The script returns the following exit codes to indicate its status:
    - 0 - `scriptSuccess`
    - 126 - `scriptFailed`
    - 130 - `scriptTerminated`

    If the `-Status` option is passed, the exit code signals the Salt minion’s
    installation status as follows:
    - 100 - Installed (and running)
    - 101 - Installing
    - 102 - Not installed
    - 103 - Installation failed
    - 104 - Removing
    - 105 - Removal failed
    - 106 - External installation detected
    - 107 - Installed but stopped

    NOTE: This script must be executed with Administrator privileges.

PARAMETERS
    -Install [<SwitchParameter>]
        The Install action downloads, installs, and starts the salt-minion
        service.

        It exits with the `scriptFailed` exit code (126) under any of the
        following conditions:
        - Existing Standard Salt Installation detected
        - Unknown status found
        - Installation in progress
        - Removal in progress
        - Installation failed
        - Missing script dependencies

        It exits with the `scriptSuccess` exit code (0) under the following
        conditions:
        - Installed successfully
        - Already installed

    -Upgrade [<SwitchParameter>]
        The Upgrade parameter upgrades an existing Salt installation in place,
        leaving the minion configuration unchanged. guestVars and CLI values
        are ignored during the upgrade. Use this option to switch between
        different Salt versions.

        Pass the Upgrade parameter with the Install action to upgrade to the
        specified version. If Upgrade is not passed and Salt is already installed,
        the script will exit with a `scriptSuccess` code (0) and a message
        indicating that the minion is already installed.

    -MinionVersion <String>
        The MinionVersion parameter specifies the version of the Salt minion to
        install. Use "latest" to install the most recent version available
        (default is "latest"). Alternatively, you can specify a major version
        number to install the latest release within that version series. For
        example, to install the latest release in the 3006 series, pass "3006".

    -Source <String>
        The Source parameter specifies the URL or path to a repository containing
        directories named after different Salt versions. Each directory should
        include a zip file corresponding to the version indicated by the directory
        name.

        The directory structure should follow a layout similar to the default
        repository:

        https://packages.broadcom.com/artifactory/saltproject-generic/onedir

        The Source parameter supports common protocols such as HTTP, HTTPS, FTP,
        UNC paths, and local file paths.

    -Reconfig [<SwitchParameter>]
        The Reconfig action updates the Salt minion configuration using settings
        provided via the command-line, `guestVars`, or `tools.conf`. After
        updating, the minion will be restarted to apply the new configuration.

        The following exit codes may occur:
        - 102 - Salt minion not installed
        - 106 - External installation of the Salt minion detected

    -ConfigOptions <String[]>
        This parameter accepts any number of minion configuration options,
        specified as key/value pairs in the format `key=value`, as documented in
        the Salt documentation. For example: master=localhost.

        All keys will be automatically converted to lowercase and written to the
        minion configuration.

        The keys `source`, `minionversion` and `loglevel` are the exception. They
        are options for this script, the same as the `-Source`, `-MinionVersion`
        and `-LogLevel` parameters. They are not written to the minion
        configuration. For example: source=https://my.domain.com/vmtools/salt
        Options end at the next parameter, a token starting with `-`.

    -Remove [<SwitchParameter>]
        The Remove action stops and uninstalls the salt-minion service. It exits
        with the `scriptFailed` exit code (126) under the following conditions:
        - Unknown status found
        - Installation in progress
        - Removal in progress
        - Installation failed
        - Missing script dependencies

        It exits with the `scriptSuccess` exit code (0) under the following
        conditions:
        - Successfully removed
        - Already removed

    -Clear [<SwitchParameter>]
        The Clear action resets the salt-minion by randomizing its minion ID and
        removing the minion keys. The new minion ID will be the old minion ID
        followed by an underscore and five random digits.

        Exits with the `scriptFailed` exit code (126) under the following
        conditions:
        - Unknown status found
        - Missing script dependencies

        Exits with the `scriptSuccess` exit code (0) under the following
        conditions:
        - Successfully cleared
        - Minion was not installed

    -Status [<SwitchParameter>]
        The Status action retrieves the current status of the Salt minion
        installation. The exit code will correspond to one of the following status
        codes:

        100 - Installed (and running)
        101 - Installing
        102 - Not installed
        103 - Installation failed
        104 - Removing
        105 - Removal failed
        106 - External installation detected
        107 - Installed but stopped

        Exits with the `scriptFailed` exit code (126) under the following
        conditions:
        - Unknown status found
        - Missing script dependencies

    -Depend [<SwitchParameter>]
        The Depend action checks that all required dependencies are available.

        It exits with the `scriptFailed` exit code (126) if any dependencies are
        missing.

        It exits with the `scriptSuccess` exit code (0) if all dependencies are
        present.

    -LogLevel <String>
        Sets the log level for display and logging. The default is "warning". The
        "silent" level suppresses all logging output. Available options are:

        - silent
        - error
        - warning
        - info
        - debug

        Logs are stored in `C:\Windows\temp` and named according to the action the
        script is performing, along with a timestamp. For example:
        `vmware-svtminion-<action>-<timestamp>.log`

    -Stop [<SwitchParameter>]
        Stops the salt-minion service.

        The following exit codes may occur:
        102 - Salt minion not installed
        106 - External installation of the Salt minion detected

    -Start [<SwitchParameter>]
        Starts or restarts the salt-minion service.

        The following exit codes may occur:
        102 - Salt minion not installed
        106 - External install of the Salt minion found

    -Help [<SwitchParameter>]
        Displays help information for this script.

    -Version [<SwitchParameter>]
        Displays the current version of this script.

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).

    -------------------------- EXAMPLE 1 --------------------------
    PS>svtminion.ps1 -Install

    -------------------------- EXAMPLE 2 --------------------------
    PS>svtminion.ps1 -Install -MinionVersion 3006.2 master=192.168.10.10 id=dev_box

    -------------------------- EXAMPLE 3 --------------------------
    PS>svtminion.ps1 -Install -Source https://my.domain.com/vmtools/salt

    -------------------------- EXAMPLE 4 --------------------------
    PS>svtminion.ps1 -Install -MinionVersion 3006.8 -Upgrade

    -------------------------- EXAMPLE 5 --------------------------
    PS>svtminion.ps1 -Clear

    -------------------------- EXAMPLE 6 --------------------------
    PS>svtminion.ps1 -Status

    -------------------------- EXAMPLE 7 --------------------------
    PS>svtminion.ps1 -Depend

    -------------------------- EXAMPLE 8 --------------------------
    PS>svtminion.ps1 -Remove -LogLevel debug

REMARKS
    To see the examples, type: "get-help .\svtminion.ps1 -examples".
    For more information, type: "get-help .\svtminion.ps1 -detailed".
    For technical information, type: "get-help .\svtminion.ps1 -full".