rooted config

* updated documentation
* troubleshooting
* Itegrated comments and feedback
* bugfixes to format and language
* linting the changes

.gitignore

@@ -64,3 +64,7 @@ _version.py
 
 # Ignore grains file written out during tests
 tests/integration/files/conf/grains
+/salt/_syspaths.py
+
+# ignore the local root
+/root/**

doc/cheatsheet/salt.tex

@@ -26,6 +26,17 @@
 
 The \texttt{top.sls} file is used to map what SLS modules get loaded onto what minions via the state system.\\
 
+It is located in the file defined in the \texttt{file_roots} variable of the
+salt master configuration file which is found in
+\texttt{CONFIG_DIR}/master.
+
+The file roots is defined like this by default.
+\begin{verbatim}
+file_roots:
+  base:
+    - /srv/salt
+\end{verbatim}
+
 Here is an example \texttt{top.sls} file which uses \texttt{pkg}, \texttt{file} and \texttt{service} states:
 
 \begin{verbatim}

doc/index.rst

@@ -67,6 +67,9 @@ States - Configuration Management with Salt:
 Masterless Quickstart:
     :doc:`Salt Quickstart </topics/tutorials/quickstart>`
 
+Running Salt without root access in userland:
+    - :doc:`Salt Usermode <topics/tutorials/rooted.rst>`
+
 A list of all tutorials can be found here:
     :doc:`All Salt tutorials <topics/tutorials/index>`
 
@@ -288,4 +291,4 @@ More information about the project
     The SaltStack security disclosure policy
 
 .. _`salt-contrib`: https://github.com/saltstack/salt-contrib
-.. _`salt-states`: https://github.com/saltstack/salt-states
+.. _`salt-states`: https://github.com/saltstack/salt-states

doc/topics/troubleshooting/master.rst

@@ -247,3 +247,30 @@ service.
     auth_timeout:
         The total time to wait for the authentication process to complete, regardless
         of the number of attempts.
+
+
+=====================
+Running state locally
+=====================
+
+To debug the states, you can use call locally.
+
+.. code-block:: bash
+
+    salt-call -l trace --local state.highstate
+
+
+The top.sls file is used to map what SLS modules get loaded onto what minions via the state system.
+
+It is located in the file defined in the file_roots variable of the salt master
+configuration file which is defined by found in CONFIG_DIR/master, normally /etc/salt/master
+
+The file roots is defined like this by default.
+
+.. code-block:: yaml
+
+   file_roots:
+     base:
+       - /srv/salt
+
+So the top file is defaulted to the location /srv/salt/top.sls

doc/topics/tutorials/rooted.rst

@@ -0,0 +1,74 @@
+====================================
+running salt as normal user tutorial
+====================================
+
+.. include:: /_incl/requisite_incl.rst
+
+Running Salt functions as non root user
+=======================================
+
+If you dont want to run salt cloud as root or even install it you can
+configure it to have a virtual root in your working directory.
+
+The salt system uses the salt.syspath module to find the variables
+
+if you run the salt-build, it will be installed like this:
+./build/lib.linux-x86_64-2.7/salt/_syspaths.py
+and produced by the command
+
+.. code-block:: bash
+
+    python setup.py build
+
+copy that into your salt dir
+
+.. code-block:: bash
+
+    cp ./build/lib.linux-x86_64-2.7/salt/_syspaths.py salt/_syspaths.py
+
+edit it to include needed variables and your new paths
+
+.. code-block:: python
+
+   # you need to edit this
+   ROOT_DIR = *your current dir* + '/salt/root'
+
+   # you need to edit this
+   INSTALL_DIR = *location of source code*
+
+   CONFIG_DIR =  ROOT_DIR + '/etc/salt'
+   CACHE_DIR = ROOT_DIR + '/var/cache/salt'
+   SOCK_DIR = ROOT_DIR + '/var/run/salt'
+   SRV_ROOT_DIR= ROOT_DIR + '/srv'
+   BASE_FILE_ROOTS_DIR = ROOT_DIR + '/srv/salt'
+   BASE_PILLAR_ROOTS_DIR = ROOT_DIR + '/srv/pillar'
+   BASE_MASTER_ROOTS_DIR = ROOT_DIR + '/srv/salt-master'
+   LOGS_DIR = ROOT_DIR + '/var/log/salt'
+   PIDFILE_DIR = ROOT_DIR + '/var/run'
+   CLOUD_DIR = INSTALL_DIR + '/cloud'
+   BOOTSTRAP = CLOUD_DIR + '/deploy/bootstrap-salt.sh'
+
+
+Create the directory structure
+
+.. code-block:: bash
+
+    mkdir -p root/etc/salt root/var/cache/run root/run/salt root/srv
+    root/srv/salt root/srv/pillar root/srv/salt-master root/var/log/salt root/var/run
+
+
+Populate the config
+
+.. code-block:: bash
+
+    cp -r conf/* root/etc/salt/
+
+edit your root/etc/salt/master config that is used by salt-cloud
+
+    user: *your user name*
+
+Run like this :
+
+.. code-block:: bash
+
+    PYTHONPATH=`pwd` scripts/salt-cloud

salt/cli/api.py

@@ -1,13 +1,21 @@
 # -*- coding: utf-8 -*-
+'''
+    salt.cli.api
+    ~~~~~~~~~~~~~
+
+    Salt's api cli parser.
+
+'''
 from __future__ import print_function
 from __future__ import absolute_import
 
 import six
 import sys
+import os.path
 import logging
-
 import salt.utils.parsers as parsers
 import salt.version
+import salt.syspaths as syspaths
 
 log = logging.getLogger(__name__)
 
@@ -25,7 +33,7 @@ class SaltAPI(six.with_metaclass(parsers.OptionParserMeta,  # pylint: disable=W0
     # ConfigDirMixIn config filename attribute
     _config_filename_ = 'master'
     # LogLevelMixIn attributes
-    _default_logging_logfile_ = '/var/log/salt/api'
+    _default_logging_logfile_ = os.path.join(syspaths.LOGS_DIR, 'api')
 
     def setup_config(self):
         return salt.config.api_config(self.get_config_file_path())

salt/cloud/cli.py

@@ -4,9 +4,9 @@
 '''
 # Need to get data from 4 sources!
 # CLI options
-# salt cloud config - /etc/salt/cloud
+# salt cloud config - CONFIG_DIR + '/cloud'
 # salt master config (for master integration)
-# salt VM config, where VMs are defined - /etc/salt/cloud.profiles
+# salt VM config, where VMs are defined - CONFIG_DIR + '/cloud.profiles'
 #
 # The cli, master and cloud configs will merge for opts
 # the VM data will be in opts['profiles']
@@ -31,7 +31,7 @@
 import salt.cloud
 from salt.exceptions import SaltCloudException, SaltCloudSystemExit
 import salt.ext.six as six
-
+import salt.syspaths as syspaths
 log = logging.getLogger(__name__)
 
 
@@ -50,9 +50,10 @@ def run(self):
                 'If salt-cloud is running on a master machine, salt-cloud '
                 'needs to run as the same user as the salt-master, {0!r}. If '
                 'salt-cloud is not running on a salt-master, the appropriate '
-                'write permissions must be granted to /etc/salt/. Please run '
+                'write permissions must be granted to {1!r}. Please run '
                 'salt-cloud as root, {0!r}, or change permissions for '
-                '/etc/salt/.'.format(salt_master_user)
+                '{1!r}.'.format(salt_master_user,
+                                syspaths.CONFIG_DIR)
             )
 
         try:

salt/scripts.py

@@ -302,7 +302,8 @@ def salt_cloud():
     try:
         import salt.cloud.cli
         has_saltcloud = True
-    except ImportError:
+    except ImportError as e:
+        log.error("Error importing salt cloud {0}".format(e))
         # No salt cloud on Windows
         has_saltcloud = False
     if '' in sys.path:

salt/syspaths.py

@@ -21,7 +21,8 @@
 from __future__ import absolute_import
 import sys
 import os.path
-
+import logging
+log = logging.getLogger(__name__)
 if 'SETUP_DIRNAME' in globals():
     # This is from the exec() call in Salt's setup.py
     THIS_FILE = os.path.join(SETUP_DIRNAME, 'salt', 'syspaths.py')  # pylint: disable=E0602
@@ -46,7 +47,8 @@
         INSTALL_DIR,
         BOOTSTRAP,
     )
-except ImportError:
+except ImportError as error:
+    log.error('Error importing salt._syspaths with exception {0}'.format(error))
     # The installation time was not generated, let's define the default values
     __platform = sys.platform.lower()
     if __platform.startswith('win'):

salt/utils/parsers.py

@@ -410,6 +410,7 @@ def _mixin_setup(self):
         config_dir = os.environ.get('SALT_CONFIG_DIR', None)
         if not config_dir:
             config_dir = syspaths.CONFIG_DIR
+            logging.getLogger(__name__).debug("SYSPATHS setup as : %s", syspaths.CONFIG_DIR)
         self.add_option(
             '-c', '--config-dir', default=config_dir,
             help=('Pass in an alternative configuration directory. Default: '
@@ -420,7 +421,7 @@ def process_config_dir(self):
         if not os.path.isdir(self.options.config_dir):
             # No logging is configured yet
             sys.stderr.write(
-                'WARNING: {0!r} directory does not exist.\n'.format(
+                'WARNING: CONFIG {0!r} directory does not exist.\n'.format(
                     self.options.config_dir
                 )
             )

setup.py

@@ -361,6 +361,8 @@ def run(self):
 
 
 INSTALL_SYSPATHS_TEMPLATE = '''\
+import os.path
+
 # This file was auto-generated by salt's setup on \
 {date:%A, %d %B %Y @ %H:%m:%S UTC}.
 
@@ -374,6 +376,9 @@ def run(self):
 BASE_MASTER_ROOTS_DIR = {base_master_roots_dir!r}
 LOGS_DIR = {logs_dir!r}
 PIDFILE_DIR = {pidfile_dir!r}
+INSTALL_DIR = {SETUP_DIRNAME}
+CLOUD_DIR = os.path.join(INSTALL_DIR, 'cloud')
+BOOTSTRAP = os.path.join(CLOUD_DIR, 'deploy', 'bootstrap-salt.sh')
 '''