docs: def shell_run(cmd,
                cin=None, cwd=None, timeout=10, critical=True, verbose=True):
      '''
      Runs a shell command within a controlled environment.
  
      .. note:: |use_photon_m|
  
      :param cmd: The command to run
  
          * A string one would type into a console like \
          :command:`git push -u origin master`.
  
          * Will be split using :py:func:`shlex.split`.
  
          * It is possible to use a list here, but then no splitting is done.
  
      :param cin:
          Add something to stdin of `cmd`
      :param cwd:
          Run `cmd` insde specified current working directory
      :param timeout:
          Catch infinite loops (e.g. ``ping``).
          Exit after `timeout` seconds
      :param critical:
          If set to ``True``: |appteardown| on failure of `cmd`
      :param verbose:
          Show messages and warnings
      :returns:
          A dictionary containing the results from
          running `cmd` with the following:
  
          * 'command': `cmd`
  
          * 'stdin': `cin` (If data was set in `cin`)
  
          * 'cwd': `cwd` (If `cwd` was set)
  
          * 'exception': exception message (If an exception was thrown)
  
          * 'timeout': `timeout` (If a timeout exception was thrown)
  
          * 'stdout': List from stdout (If any)
  
          * 'stderr': List from stderr (If any)
  
          * 'returncode': The returncode (If not any exception)
  
          * 'out': The most urgent message as joined string. \
          ('exception' > 'stderr' > 'stdout')
      '''
  
      res = dict(command=cmd)
      if cin:
          cin = str(cin)
          res.update(dict(stdin=cin))
      if cwd:
          res.update(dict(cwd=cwd))
  
      if isinstance(cmd, str):
          cmd = _split(cmd)
  
      try:
          p = _Popen(
              cmd, stdin=_PIPE, stdout=_PIPE, stderr=_PIPE,
              bufsize=1, cwd=cwd, universal_newlines=True
          )
      except Exception as ex:
          res.update(dict(exception=str(ex)))
      else:
  
          try:
              out, err = p.communicate(input=cin, timeout=timeout)
              if out:
                  res.update(dict(
                      stdout=[o for o in out.split('\n') if o]
                  ))
              if err:
                  res.update(dict(
                      stderr=[e for e in err.split('\n') if e]
                  ))
              res.update(dict(returncode=p.returncode))
  
          except _TimeoutExpired as ex:
              res.update(dict(exception=str(ex), timeout=timeout))
              p.kill()
          except Exception as ex:
              res.update(dict(exception=str(ex)))
  
      res.update(
          out=(
              res.get('exception') or
              '\n'.join(res.get('stderr') or res.get('stdout', ''))
          )
      )
  
      if res.get('returncode', -1) != 0:
          res.update(dict(critical=critical))
  
          shell_notify(
              'error in shell command \'%s\'' % (res.get('command')),
              state=True if critical else None,
              more=res,
              verbose=verbose
          )
  
      return res