docs: def halted(name, graceful=True):
      '''
      Ensure zone is halted
  
      name : string
          name of the zone
      graceful : boolean
          use shutdown instead of halt if true
  
      '''
      ret = {'name': name,
             'changes': {},
             'result': None,
             'comment': ''}
  
      zones = __salt__['zoneadm.list'](installed=True)
      if name in zones:
          ## zone exists
          if zones[name]['state'] != 'running':
              ## zone is not running
              ret['result'] = True
              ret['comment'] = 'Zone {0} already halted'.format(name)
          else:
              ## try and halt the zone
              if not __opts__['test']:
                  zoneadm_res = __salt__['zoneadm.shutdown'](name) if graceful else __salt__['zoneadm.halt'](name)
              if __opts__['test'] or zoneadm_res['status']:
                  ret['result'] = True
                  ret['changes'][name] = 'halted'
                  ret['comment'] = 'Zone {0} halted'.format(name)
              else:
                  ret['result'] = False
                  ret['comment'] = 'Failed to halt {0}'.format(name)
      else:
          ## zone does not exist
          ret['comment'] = []
          ret['comment'].append(
              'The zone {0} is not in the installed state.'.format(name)
          )
          for zone in zones:
              if zones[zone]['uuid'] == name:
                  ret['comment'].append(
                      'The zone {0} has a uuid of {1}, please use the zone name instead!'.format(
                          zone,
                          name,
                      )
                  )
          ## note: a non existing zone is not running, we do not consider this a failure
          ret['result'] = True
          ret['comment'] = "\n".join(ret['comment'])
  
      return ret