salt.modules.system

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

Note

If you have configured a wrapper such as molly-guard to intercept interactive shutdown commands, be aware that 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 if this 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 '*' network.get_hostname
salt.modules.system.get_reboot_required_witnessed()

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.

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.

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 (+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.

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 returns False.

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()

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

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 you don't pass the year, the current system year will be used. (Used by set_system_date and set_system_time)

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

Parameters
  • years (int) -- Years digit, ie: 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.

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 you may have to quote the text twice from 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.

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