Merge remote-tracking branch 'upstream/develop' into feature_mknod

doc/contents.rst

@@ -6,6 +6,8 @@ Full Table of Contents
     :maxdepth: 3
     :glob:
 
+    faq
+
     topics/index
     topics/installation/index
     topics/configuration
@@ -30,6 +32,8 @@ Full Table of Contents
     topics/git/*
     topics/development/index
 
+    ref/configuration/logging/*
+    ref/configuration/logging/handlers/*
     ref/index
     ref/modules/*
     ref/modules/all/index

doc/faq.rst

@@ -0,0 +1,39 @@
+Frequently Asked Questions
+==========================
+
+Is Salt open-core?
+------------------
+
+No. Salt is 100% committed to being open-source, including all of our APIs and
+the new `'Halite' web interface`_ which will be included in version 0.17.0. It
+is developed under the `Apache 2.0 license`_, allowing it to be used in both
+open and proprietary projects.
+
+.. _`'Halite' web interface`: https://github.com/saltstack/halite
+.. _`Apache 2.0 license`: http://www.apache.org/licenses/LICENSE-2.0.html
+
+What ports should I open on my firewall?
+----------------------------------------
+
+Minions need to be able to connect to the master on TCP ports 4505 and 4506.
+Minions do not need any inbound ports open. More detailed information on
+firewall settings can be found :doc:`here </topics/tutorials/firewall>`.
+
+Should I use :mod:`cmd.run <salt.states.cmd.run>` or :mod:`cmd.wait <salt.states.cmd.wait>`?
+----------------------------------------------------------------------------------------------------
+
+These states are often confused. A description of the difference between the
+two can be found in the docmentation for the :mod:`cmd states
+<salt.states.cmd>`.
+
+How does Salt guess the Minion's hostname?
+------------------------------------------
+
+This process is explained in detail :ref:`here <minion-id-generation>`.
+
+Why aren't my custom modules/states/etc. syncing to my Minions?
+---------------------------------------------------------------
+
+If you are using the :doc:`git fileserver backend </topics/tutorials/gitfs>`,
+and Salt 0.16.3 or older, then this may be due to a bug in gitfs. More
+information about this can be found :ref:`here <faq-gitfs-bug>`.

doc/index.rst

@@ -232,14 +232,19 @@ Reference
 :doc:`Full table of contents </contents>`
     Dense but complete.
 
+FAQ
+===
+
+See :doc:`here <faq>` for a list of Frequently Asked Questions.
+
 More information about the project
-----------------------------------
+==================================
 
 :doc:`Release notes </topics/releases/index>`
     Living history of Salt Stack.
 
 :doc:`Community </topics/community>`
-    How to can get involved.
+    How to get involved.
 
 :doc:`Salt Development </topics/development/index>`
     Information for Hacking on Salt

doc/ref/modules/all/index.rst

@@ -82,6 +82,7 @@ Full list of builtin execution modules
     localemod
     locate
     logrotate
+    lxc
     makeconf
     match
     mdadm
@@ -135,6 +136,7 @@ Full list of builtin execution modules
     rvm
     s3
     saltutil
+    seed
     selinux
     service
     shadow

doc/ref/modules/all/salt.modules.seed.rst

@@ -1,6 +1,6 @@
-================
+=================
 salt.modules.seed
-================
+=================
 
 .. automodule:: salt.modules.seed
     :members:

doc/ref/windows-package-manager.rst

@@ -293,5 +293,12 @@ updated the repository cache on the relevant minions:
 
     salt-run winrepo.genrepo
     salt 'MINION' pkg.refresh_db
+    
+    
+Packages management under Windows 2003
+----------------------------------------
 
+On windows server 2003, you need to install optional windows component 
+"wmi windows installer provider" to have full list of installed packages.
+If you don't have this, salt-minion can't report some installed softwares.
 

doc/topics/installation/windows.rst

@@ -236,6 +236,11 @@ You can execute the above command remotely from a Linux host using winexe:
 
 For more info check `http://csa-net.dk/salt`_
 
+Packages management under Windows 2003
+======================================
+
+On windows server 2003, you need to install optional component "wmi windows installer provider" to have full list of installed packages. If you don't have this, salt-minion can't report some installed softwares.
+
 
 .. _http://csa-net.dk/salt: http://csa-net.dk/salt
 .. _msysgit: http://code.google.com/p/msysgit/downloads/list?can=3

doc/topics/tutorials/gitfs.rst

@@ -173,3 +173,18 @@ for the user running the salt-master.
 .. note::
 
     GitFS requires the Python module ``GitPython``, version 0.3.0 or newer.
+
+.. _faq-gitfs-bug:
+
+Why aren't my custom modules/states/etc. syncing to my Minions?
+===============================================================
+
+In versions 0.16.3 and older, when using the :doc:`git fileserver backend
+</topics/tutorials/gitfs>`, certain versions of GitPython may generate errors
+when fetching, which Salt fails to catch. While not fatal to the fetch process,
+these interrupt the fileserver update that takes place before custom types are
+synced, and thus interrupt the sync itself. Try disabling the git fileserver
+backend in the master config, restarting the master, and attempting the sync
+again.
+
+This issue will be worked around in Salt 0.16.4 and newer.

doc/topics/tutorials/walkthrough.rst

@@ -168,7 +168,8 @@ When the minion is started, it will generate an ``id`` value. This is the name
 by which the minion will attempt to authenticate to the master. The following
 steps are attempted, in order to try to find a value that is not ``localhost``:
 
-1. ``/etc/hostname`` is checked (non-Windows only)
+1. ``/etc/hostname`` is checked (non-Windows only) **Note: Not used currently,
+   will be as of version 0.17.0.**
 2. The Python function ``socket.getfqdn()`` is run
 3. ``/etc/hosts`` (``%WINDIR%\system32\drivers\etc\hosts`` on Windows hosts) is
    checked for hostnames that map to anything within :strong:`127.0.0.0/8`.

salt/log/handlers/logstash_mod.py

@@ -105,7 +105,7 @@
     .. _`ZeroMQ input`: http://logstash.net/docs/latest/inputs/zeromq
     .. _`high water mark`: http://api.zeromq.org/3-2:zmq-setsockopt
 
-    :codeauthor: :email:`Pedro Algarvio (pedro@algarvio.me)`
+    :codeauthor: Pedro Algarvio (pedro@algarvio.me)
     :copyright: © 2013 by the SaltStack Team, see AUTHORS for more details.
     :license: Apache 2.0, see LICENSE for more details.
 '''

salt/log/handlers/sentry_mod.py

@@ -59,7 +59,7 @@
     .. _`Raven client documentation`: http://raven.readthedocs.org/en/latest/config/index.html#client-arguments
 
 
-    :codeauthor: :email:`Pedro Algarvio (pedro@algarvio.me)`
+    :codeauthor: Pedro Algarvio (pedro@algarvio.me)
     :copyright: © 2013 by the SaltStack Team, see AUTHORS for more details.
     :license: Apache 2.0, see LICENSE for more details.
 '''

salt/modules/lxc.py

@@ -7,6 +7,7 @@ Work with linux containers
 # Import python libs
 import logging
 import tempfile
+import os
 
 #import salt libs
 import salt.utils
@@ -100,9 +101,9 @@ def init(name,
 
     .. code-block:: bash
 
-        salt 'minion' lxc.init name [cpuset=cgroups_cpuset] \
-                [cpushare=cgroups_cpushare] [memory=cgroups_memory] \
-                [nic=nic_profile] [profile=lxc_profile] \
+        salt 'minion' lxc.init name [cpuset=cgroups_cpuset] \\
+                [cpushare=cgroups_cpushare] [memory=cgroups_memory] \\
+                [nic=nic_profile] [profile=lxc_profile] \\
                 [state=(true|false)]
 
     name
@@ -146,9 +147,9 @@ def create(name, config=None, profile=None, options=None, **kwargs):
 
     .. code-block:: bash
 
-        salt 'minion' lxc.create name [config=config_file] \
-                [profile=profile] [template=template_name] \
-                [backing=backing_store] [ vgname=volume_group] \
+        salt 'minion' lxc.create name [config=config_file] \\
+                [profile=profile] [template=template_name] \\
+                [backing=backing_store] [ vgname=volume_group] \\
                 [size=filesystem_size] [options=template_options]
 
     name
@@ -342,11 +343,11 @@ def exists(name):
 
 def state(name):
     '''
-    Returns information about a container.
+    Returns the state of a container.
 
     .. code-block:: bash
 
-        salt '*' lxc.info name
+        salt '*' lxc.state name
     '''
     if not exists(name):
         return None
@@ -359,3 +360,51 @@ def state(name):
         lines = ret['stdout'].splitlines()
         r = dict([l.split() for l in lines])
         return r['state:'].lower()
+
+
+def info(name):
+    '''
+    Returns information about a container.
+
+    .. code-block:: bash
+
+        salt '*' lxc.info name
+    '''
+    f = '/var/lib/lxc/{0}/config'.format(name)
+    cgroup_dir = '/sys/fs/cgroup/memory/lxc/{0}/'.format(name)
+    if not os.path.isfile(f):
+        return None
+
+    ret = {}
+
+    config = [(v[0].strip(), v[1].strip()) for v in
+              [l.split('#', 1)[0].strip().split('=', 1) for l in
+               open(f).readlines()] if len(v) == 2]
+
+    ifaces = []
+    current = None
+
+    for k, v in config:
+        if k == 'lxc.network.type':
+            current = {'type': v}
+            ifaces.append(current)
+        elif not current:
+            continue
+        elif k.startswith('lxc.network.'):
+            current[k.replace('lxc.network.', '', 1)] = v
+    if ifaces:
+        ret['ifaces'] = ifaces
+
+    ret['rootfs'] = next((i[1] for i in config if i[0] == 'lxc.rootfs'), None)
+    ret['state'] = state(name)
+
+    if ret['state'] == 'running':
+        with open(cgroup_dir + 'memory.limit_in_bytes') as f:
+            limit = int(f.read())
+        with open(cgroup_dir + 'memory.usage_in_bytes') as f:
+            memory = int(f.read())
+        free = limit - memory
+        ret['memory_limit'] = limit
+        ret['memory_free'] = free
+
+    return ret

salt/modules/seed.py

@@ -53,8 +53,8 @@ def apply(path, id_=None, config=None, approve_key=True, install=True):
 
     .. code-block:: bash
 
-        salt 'minion' seed.whatever path id [config=config_data] \
-                [gen_key=(true|false)] [approve_key=(true|false)] \
+        salt 'minion' seed.whatever path id [config=config_data] \\
+                [gen_key=(true|false)] [approve_key=(true|false)] \\
                 [install=(true|false)]
 
     path

salt/states/cmd.py

@@ -1,6 +1,6 @@
 '''
-Execution of arbitrary commands.
-================================
+Execution of arbitrary commands
+===============================
 
 The cmd state module manages the enforcement of executed commands, this
 state can tell a command to run under certain circumstances.
@@ -103,6 +103,33 @@ it can also watch a git state for changes
           - git: my-project
 
 
+Should I use :mod:`cmd.run <salt.states.cmd.run>` or :mod:`cmd.wait <salt.states.cmd.wait>`?
+--------------------------------------------------------------------------------------------
+
+These two states are often confused. The important thing to remember about them
+is that :mod:`cmd.run <salt.states.cmd.run>` states are run each time the SLS
+file that contains them is applied. If it is more desirable to have a command
+that only runs after some other state changes, then :mod:`cmd.wait
+<salt.states.cmd.wait>` does just that. :mod:`cmd.wait <salt.states.cmd.wait>`
+is designed to be :doc:`watched </ref/states/requisites>` by other states, and
+executed when the state watching it changes. Example:
+
+.. code-block:: yaml
+
+    /usr/local/bin/postinstall.sh:
+      cmd:
+        - wait
+      file:
+        - managed
+        - source: salt://utils/scripts/postinstall.sh
+
+    mycustompkg:
+      pkg:
+        - installed
+        - watch:
+          - cmd: /usr/local/bin/postinstall.sh
+        - require:
+          - file: /usr/local/bin/postinstall.sh
 '''
 
 # Import python libs
@@ -774,7 +801,7 @@ def mod_watch(name, **kwargs):
             func = kwargs.pop('func')
             return call(name, func, **kwargs)
         else:
-            return {'name': name, 
+            return {'name': name,
                     'changes': {},
                     'comment': 'cmd.{0[sfun]} needs a named parameter func'.format(kwargs),
                     'result': False}

salt/states/pkg.py

@@ -1,6 +1,6 @@
 '''
-Installation of packages using OS package managers such as yum or apt-get.
-==========================================================================
+Installation of packages using OS package managers such as yum or apt-get
+=========================================================================
 
 Salt can manage software packages via the pkg state module, packages can be
 set up to be installed, latest, removed and purged. Package management

salt/tops/reclass_adapter.py

@@ -1,9 +1,9 @@
 '''
 .. |reclass| replace:: **reclass**
 
-This :doc:`master_tops <../../../topics/master_tops>` plugin provides
-access to the |reclass| database, such that state information (top
-data) are retrieved from |reclass|.
+This :doc:`master_tops </topics/master_tops/index>` plugin provides access to
+the |reclass| database, such that state information (top data) are retrieved
+from |reclass|.
 
 You can find more information about |reclass| at
 http://reclass.pantsfullofunix.net.
@@ -55,6 +55,9 @@ from salt.utils.reclass import (
     set_inventory_base_uri_default
 )
 
+from salt.exceptions import SaltInvocationError
+
+
 def __virtual__(retry=False):
     try:
         import reclass
@@ -67,7 +70,6 @@ def __virtual__(retry=False):
         prepend_reclass_source_path(opts)
         return __virtual__(retry=True)
 
-from salt.exceptions import SaltInvocationError
 
 def top(**kwargs):
     '''