Clone the repository using:
git clone https://github.com/saltstack/salt
Just cloning the repository is enough to work with Salt and make contributions. However, fetching additional tags from git is required to have Salt report the correct version for itself. To do this, first add the git repository as an upstream source:
git remote add upstream https://github.com/saltstack/salt
Fetching tags is done with the git 'fetch' utility:
git fetch --tags upstream
Create a new virtualenv:
Avoid making your virtualenv path too long.
On Arch Linux, where Python 3 is the default installation of Python, use
virtualenv2 command instead of
On Gentoo you must use
--system-site-packages to enable pkg and portage_config
Using system Python modules in the virtualenv
To use already-installed python modules in virtualenv (instead of having pip
download and compile new ones), run
Using this method eliminates the requirement to install the salt dependencies
again, although it does assume that the listed modules are all installed in the
system PYTHONPATH at the time of virtualenv creation.
Python development package
Be sure to install python devel package in order to install required Python
modules. In Debian/Ubuntu run
sudo apt-get install -y python-dev. In RedHat
based system install
Activate the virtualenv:
Install Salt (and dependencies) into the virtualenv:
pip install M2Crypto # Don't install on Debian/Ubuntu (see below) pip install pyzmq PyYAML pycrypto msgpack-python jinja2 psutil futures tornado pip install -e ./salt # the path to the salt git clone from above
libssl-dev are required to build M2Crypto. To fix
command 'swig' failed with exit status 1 while installing M2Crypto,
try installing it with the following command:
env SWIG_FEATURES="-cpperraswarn -includeall -D__`uname -m`__ -I/usr/include/openssl" pip install M2Crypto
Debian and Ubuntu systems have modified openssl libraries and mandate that a patched version of M2Crypto be installed. This means that M2Crypto needs to be installed via apt:
apt-get install python-m2crypto
This also means that pulling in the M2Crypto installed using apt requires using
--system-site-packages when creating the virtualenv.
If you're using a platform other than Debian or Ubuntu, and you are
installing M2Crypto via pip instead of a system package, then you will also
Python header files are required to build this module, otherwise the pip
install will fail. If your distribution separates binaries and headers into
separate packages, make sure that you have the headers installed. In most
Linux distributions which split the headers into their own package, this
can be done by installing the
For other platforms, the package will likely be similarly named.
Installing dependencies on macOS.
You can install needed dependencies on macOS using homebrew or macports. See macOS Installation
Installing on RedHat-based Distros
If installing from pip (or from source using
setup.py install), be
advised that the
yum-utils package is needed for Salt to manage
packages on RedHat-based systems.
During development it is easiest to be able to run the Salt master and minion that are installed in the virtualenv you created above, and also to have all the configuration, log, and cache files contained in the virtualenv as well.
Copy the master and minion config files into your virtualenv:
mkdir -p /path/to/your/virtualenv/etc/salt cp ./salt/conf/master ./salt/conf/minion /path/to/your/virtualenv/etc/salt/
Edit the master config file:
user: rootvalue to your own user.
root_dir: /value to point to
pidfile: /var/run/salt-master.pidvalue to point to
ret_portvalues as well.
Edit the minion config file:
root_dirvalues as well as any port changes.
pidfile: /var/run/salt-minion.pidvalue to point to
master: saltvalue to point at
id:value to something descriptive like "saltdev". This isn't strictly necessary but it will serve as a reminder of which Salt installation you are working with.
ret_portvalue in the master config because you are also running a non-development version of Salt, then you will have to change the
master_portvalue in the minion config to match.
Using salt-call with a Standalone Minion
If you plan to run salt-call with this self-contained development
environment in a masterless setup, you should invoke salt-call with
-c /path/to/your/virtualenv/etc/salt so that salt can find the minion
config file. Without the
-c option, Salt finds its config files in
Start the master and minion, accept the minion's key, and verify your local Salt installation is working:
cd /path/to/your/virtualenv salt-master -c ./etc/salt -d salt-minion -c ./etc/salt -d salt-key -c ./etc/salt -L salt-key -c ./etc/salt -A salt -c ./etc/salt '*' test.ping
Running the master and minion in debug mode can be helpful when developing. To
do this, add
-l debug to the calls to
If you would like to log to the console instead of to the log file, remove the
Too long socket path?
Once the minion starts, you may see an error like the following:
zmq.core.error.ZMQError: ipc path "/path/to/your/virtualenv/ var/run/salt/minion/minion_event_7824dcbcfd7a8f6755939af70b96249f_pub.ipc" is longer than 107 characters (sizeof(sockaddr_un.sun_path)).
This means that the path to the socket the minion is using is too long. This is a system limitation, so the only workaround is to reduce the length of this path. This can be done in a couple different ways:
sock_dirminion config variable and reduce its length. Remember that this path is relative to the value you set in
NOTE: The socket path is limited to 107 characters on Solaris and Linux,
and 103 characters on BSD-based systems.
File descriptor limits
Ensure that the system open file limit is raised to at least 2047:
# check your current limit ulimit -n # raise the limit. persists only until reboot # use 'limit descriptors 2047' for c-shell ulimit -n 2047
To set file descriptors on macOS, refer to the macOS Installation instructions.
Instead of updating your configuration files to point to the new root directory and having to pass the new configuration directory path to all of Salt's CLI tools, you can explicitly tweak the default system paths that Salt expects:
GENERATE_SALT_SYSPATHS=1 pip install --global-option='--salt-root-dir=/path/to/your/virtualenv/' \ -e ./salt # the path to the salt git clone from above
You can now call all of Salt's CLI tools without explicitly passing the configuration directory.
In case you want to distribute your virtualenv, you probably don't want to
include Salt's clone
.git/ directory, and, without it, Salt won't report
the accurate version. You can tell
setup.py to generate the hardcoded
version information which is distributable:
GENERATE_SALT_SYSPATHS=1 WRITE_SALT_VERSION=1 pip install --global-option='--salt-root-dir=/path/to/your/virtualenv/' \ -e ./salt # the path to the salt git clone from above
Instead of passing those two environmental variables, you can just pass a single one which will trigger the other two:
MIMIC_SALT_INSTALL=1 pip install --global-option='--salt-root-dir=/path/to/your/virtualenv/' \ -e ./salt # the path to the salt git clone from above
This last one will grant you an editable salt installation with hardcoded system paths and version information.
If you are installing using
easy_install, you will need to define a
USE_SETUPTOOLS environment variable, otherwise dependencies will not
USE_SETUPTOOLS=1 easy_install salt
sphinx-build command to build the docs. In Debian/Ubuntu this is
provided in the
python-sphinx package. Sphinx can also be installed
to a virtualenv using pip:
pip install Sphinx==1.3.1
Change to salt documentation directory, then:
cd doc; make html
makewithout any arguments to see the available make targets, which include html, man, and text.
make SPHINXBUILD=sphinx-build2 html
make SPHINXBUILD=sphinx-build html
Once you've updated the documentation, you can run the following command to launch a simple Python HTTP server to see your changes:
cd _build/html; python -m SimpleHTTPServer
Run the test suite with following command:
See here for more information regarding the test suite.