# salt.modules.system

Support for reboot, shutdown, etc on POSIX-like systems.

Note

If a wrapper such as `molly-guard` to intercept interactive shutdown commands is configured, calling `system.halt`, `system.poweroff`, `system.reboot`, and `system.shutdown` with `salt-call` will hang indefinitely while the wrapper script waits for user input. Calling them with `salt` will work as expected.

salt.modules.system.get_computer_desc()

  Get `PRETTY_HOSTNAME` value stored in `/etc/machine-info` If this file doesn't exist or the variable doesn't exist return `False`.

  Returns:

    Value of `PRETTY_HOSTNAME` in `/etc/machine-info`. If file/variable does not exist `False`.

  Return type:

    str

  CLI Example:

      salt '*' system.get_computer_desc

salt.modules.system.get_computer_name()

  Get hostname.

  CLI Example:

      salt '*' system.get_computer_name

salt.modules.system.get_reboot_required_witnessed()

  Note

  This only applies to Minions running on NI Linux RT

  Determine if at any time during the current boot session the salt minion witnessed an event indicating that a reboot is required.

  Returns:

    `True` if the a reboot request was witnessed, `False` otherwise

  Return type:

    bool

  CLI Example:

      salt '*' system.get_reboot_required_witnessed

salt.modules.system.get_system_date(utc_offset=None)

  Get the system date

  Parameters:

    utc_offset (str) -- The UTC offset in 4 digit (`+0600`) format with an optional sign (`+`/`-`). Will default to `None` which will use the local timezone. To set the time based off of UTC use `+0000`. Note: If being passed through the command line will need to be quoted twice to allow negative offsets (e.g. `"'+0000'"`).

  Returns:

    Returns the system date.

  Return type:

    str

  CLI Example:

      salt '*' system.get_system_date

salt.modules.system.get_system_date_time(utc_offset=None)

  Get the system date/time.

  Parameters:

    utc_offset (str) -- The UTC offset in 4 digit (`+0600`) format with an optional sign (`+`/`-`). Will default to `None` which will use the local timezone. To set the time based off of UTC use `+0000`. Note: If being passed through the command line will need to be quoted twice to allow negative offsets (e.g. `"'+0000'"`).

  Returns:

    Returns the system time in `YYYY-MM-DD hh:mm:ss` format.

  Return type:

    str

  CLI Example:

      salt '*' system.get_system_date_time "'-0500'"

salt.modules.system.get_system_time(utc_offset=None)

  Get the system time.

  Parameters:

    utc_offset (str) -- The UTC offset in 4 digit (e.g. `+0600`) format with an optional sign (`+`/`-`). Will default to `None` which will use the local timezone. To set the time based off of UTC use `+0000`. Note: If being passed through the command line will need to be quoted twice to allow negative offsets (e.g. `"'+0000'"`).

  Returns:

    Returns the system time in `HH:MM:SS AM/PM` format.

  Return type:

    str

  CLI Example:

      salt '*' system.get_system_time

salt.modules.system.halt()

  Halt a running system

  CLI Example:

      salt '*' system.halt

salt.modules.system.has_settable_hwclock()

  Returns `True` if the system has a hardware clock capable of being set from software.

  CLI Example:

      salt '*' system.has_settable_hwclock

salt.modules.system.init(runlevel)

  Change the system runlevel on sysV compatible systems

  CLI Example:

      salt '*' system.init 3

salt.modules.system.poweroff()

  Poweroff a running system

  CLI Example:

      salt '*' system.poweroff

salt.modules.system.reboot(at_time=None)

  Reboot the system

  at_time

    The wait time in minutes before the system will be rebooted.

  CLI Example:

      salt '*' system.reboot

salt.modules.system.set_computer_desc(desc)

  Set `PRETTY_HOSTNAME` value stored in `/etc/machine-info` This will create the file if it does not exist. If it is unable to create or modify this file, `False` is returned.

  Parameters:

    desc (str) -- The computer description

  Returns:

    `False` on failure. `True` if successful.

  CLI Example:

      salt '*' system.set_computer_desc "Michael's laptop"

salt.modules.system.set_computer_name(hostname)

  Modify hostname.

  CLI Example:

      salt '*' system.set_computer_name master.saltstack.com

salt.modules.system.set_reboot_required_witnessed()

  Note

  This only applies to Minions running on NI Linux RT

  This function is used to remember that an event indicating that a reboot is required was witnessed. This function writes to a temporary filesystem so the event gets cleared upon reboot.

  Returns:

    `True` if successful, otherwise `False`

  Return type:

    bool

  CLI Example:

      salt '*' system.set_reboot_required_witnessed

salt.modules.system.set_system_date(newdate, utc_offset=None)

  Set the system date. Use `<mm-dd-yy>` format for the date.

  Parameters:

    newdate (str) --

    The date to set. Can be any of the following formats:

    - `YYYY-MM-DD`

    - `MM-DD-YYYY`

    - `MM-DD-YY`

    - `MM/DD/YYYY`

    - `MM/DD/YY`

    - `YYYY/MM/DD`

  CLI Example:

      salt '*' system.set_system_date '03-28-13'

salt.modules.system.set_system_date_time(years=None, months=None, days=None, hours=None, minutes=None, seconds=None, utc_offset=None)

  Set the system date and time. Each argument is an element of the date, but not required. If an element is not passed, the current system value for that element will be used. For example, if the year is not passed, the current system year will be used. (Used by `system.set_system_date` and `system.set_system_time`)

  Updates hardware clock, if present, in addition to software (kernel) clock.

  Parameters:

    - years (int) -- Years digit, e.g.: `2015`

    - months (int) -- Months digit: `1`-`12`

    - days (int) -- Days digit: `1`-`31`

    - hours (int) -- Hours digit: `0`-`23`

    - minutes (int) -- Minutes digit: `0`-`59`

    - seconds (int) -- Seconds digit: `0`-`59`

    - utc_offset (str) -- The UTC offset in 4 digit (`+0600`) format with an optional sign (`+`/`-`). Will default to `None` which will use the local timezone. To set the time based off of UTC use `+0000`. Note: If being passed through the command line will need to be quoted twice to allow negative offsets (e.g. `"'+0000'"`).

  Returns:

    `True` if successful. Otherwise `False`.

  Return type:

    bool

  CLI Example:

      salt '*' system.set_system_date_time 2015 5 12 11 37 53 "'-0500'"

salt.modules.system.set_system_time(newtime, utc_offset=None)

  Set the system time.

  Parameters:

    - newtime (str) --

      The time to set. Can be any of the following formats.

      - `HH:MM:SS AM/PM`

      - `HH:MM AM/PM`

      - `HH:MM:SS` (24 hour)

      - `HH:MM` (24 hour)

      Note that the Salt command line parser parses the date/time before we obtain the argument (preventing us from doing UTC) Therefore the argument must be passed in as a string. Meaning the text might have to be quoted twice on the command line.

    - utc_offset (str) -- The UTC offset in 4 digit (`+0600`) format with an optional sign (`+`/`-`). Will default to `None` which will use the local timezone. To set the time based off of UTC use `+0000`. Note: If being passed through the command line will need to be quoted twice to allow negative offsets (e.g. `"'+0000'"`)

  Returns:

    Returns `True` if successful. Otherwise `False`.

  Return type:

    bool

  CLI Example:

      salt '*' system.set_system_time "'11:20'"

salt.modules.system.shutdown(at_time=None)

  Shutdown a running system

  at_time

    The wait time in minutes before the system will be shutdown.

  CLI Example:

      salt '*' system.shutdown 5