# salt.modules.ps

A salt interface to psutil, a system and process library. See http://code.google.com/p/psutil.

depends:

  - python-utmp package (optional)

salt.modules.ps.boot_time(time_format=None)

  Return the boot time in number of seconds since the epoch began.

  CLI Example:

  time_format

    Optionally specify a strftime format string. Use `time_format='%c'` to get a nicely-formatted locale specific date and time (i.e. `Fri May 2 19:08:32 2014`).

    Added in version 2014.1.4.

      salt '*' ps.boot_time

salt.modules.ps.cpu_percent(interval=0.1, per_cpu=False)

  Return the percent of time the CPU is busy.

  interval

    the number of seconds to sample CPU usage over

  per_cpu

    if True return an array of CPU percent busy for each CPU, otherwise aggregate all percents into one number

  CLI Example:

      salt '*' ps.cpu_percent

salt.modules.ps.cpu_times(per_cpu=False)

  Return the percent of time the CPU spends in each state, e.g. user, system, idle, nice, iowait, irq, softirq.

  per_cpu

    if True return an array of percents for each CPU, otherwise aggregate all percents into one number

  CLI Example:

      salt '*' ps.cpu_times

salt.modules.ps.disk_io_counters(device=None)

  Return disk I/O statistics.

  CLI Example:

      salt '*' ps.disk_io_counters

      salt '*' ps.disk_io_counters device=sda1

salt.modules.ps.disk_partition_usage(all=False)

  Return a list of disk partitions plus the mount point, filesystem and usage statistics.

  CLI Example:

      salt '*' ps.disk_partition_usage

salt.modules.ps.disk_partitions(all=False)

  Return a list of disk partitions and their device, mount point, and filesystem type.

  all

    if set to False, only return local, physical partitions (hard disk, USB, CD/DVD partitions). If True, return all filesystems.

  CLI Example:

      salt '*' ps.disk_partitions

salt.modules.ps.disk_usage(path)

  Given a path, return a dict listing the total available space as well as the free space, and used space.

  CLI Example:

      salt '*' ps.disk_usage /home

salt.modules.ps.get_pid_list()

  Return a list of process ids (PIDs) for all running processes.

  CLI Example:

      salt '*' ps.get_pid_list

salt.modules.ps.get_users()

  Return logged-in users.

  CLI Example:

      salt '*' ps.get_users

salt.modules.ps.kill_pid(pid, signal=15)

  Kill a process by PID.

      salt 'minion' ps.kill_pid pid [signal=signal_number]

  pid

    PID of process to kill.

  signal

    Signal to send to the process. See manpage entry for kill for possible values. Default: 15 (SIGTERM).

  Example:

  Send SIGKILL to process with PID 2000:

      salt 'minion' ps.kill_pid 2000 signal=9

salt.modules.ps.lsof(name)

  Retrieve the lsof information of the given process name.

  CLI Example:

      salt '*' ps.lsof apache2

salt.modules.ps.netstat(name)

  Retrieve the netstat information of the given process name.

  CLI Example:

      salt '*' ps.netstat apache2

salt.modules.ps.network_io_counters(interface=None)

  Return network I/O statistics.

  CLI Example:

      salt '*' ps.network_io_counters

      salt '*' ps.network_io_counters interface=eth0

salt.modules.ps.num_cpus()

  Return the number of CPUs.

  CLI Example:

      salt '*' ps.num_cpus

salt.modules.ps.pgrep(pattern, user=None, full=False, pattern_is_regex=False)

  Return the pids for processes matching a pattern.

  If full is true, the full command line is searched for a match, otherwise only the name of the command is searched.

      salt '*' ps.pgrep pattern [user=username] [full=(true|false)]

  pattern

    Pattern to search for in the process list.

  user

    Limit matches to the given username. Default: All users.

  full

    A boolean value indicating whether only the name of the command or the full command line should be matched against the pattern.

  pattern_is_regex

    This flag enables ps.pgrep to mirror the regex search functionality found in the pgrep command line utility.

    Added in version 3001.

  Examples:

  Find all httpd processes on all 'www' minions:

      salt 'www.*' ps.pgrep httpd

  Find all bash processes owned by user 'tom':

      salt '*' ps.pgrep bash user=tom

salt.modules.ps.pkill(pattern, user=None, signal=15, full=False)

  Kill processes matching a pattern.

      salt '*' ps.pkill pattern [user=username] [signal=signal_number] \
              [full=(true|false)]

  pattern

    Pattern to search for in the process list.

  user

    Limit matches to the given username. Default: All users.

  signal

    Signal to send to the process(es). See manpage entry for kill for possible values. Default: 15 (SIGTERM).

  full

    A boolean value indicating whether only the name of the command or the full command line should be matched against the pattern.

  Examples:

  Send SIGHUP to all httpd processes on all 'www' minions:

      salt 'www.*' ps.pkill httpd signal=1

  Send SIGKILL to all bash processes owned by user 'tom':

      salt '*' ps.pkill bash signal=9 user=tom

salt.modules.ps.proc_info(pid, attrs=None)

  Return a dictionary of information for a process id (PID).

  CLI Example:

      salt '*' ps.proc_info 2322
      salt '*' ps.proc_info 2322 attrs='["pid", "name"]'

  pid

    PID of process to query.

  attrs

    Optional list of desired process attributes. The list of possible attributes can be found here: https://psutil.readthedocs.io/en/latest/#processes

salt.modules.ps.psaux(name)

  Retrieve information corresponding to a "ps aux" filtered with the given pattern. It could be just a name or a regular expression (using python search from "re" module).

  CLI Example:

      salt '*' ps.psaux www-data.+apache2

salt.modules.ps.ss(name)

  Retrieve the ss information of the given process name.

  CLI Example:

      salt '*' ps.ss apache2

  Added in version 2016.11.6.

salt.modules.ps.status(status)

  Added in version 3006.0.

  Returns a list of processes according to their state.

  CLI Example:

      salt '*' ps.status STATUS

  where `STATUS` is one of

  - running

  - sleeping

  - disk_sleep

  - stopped

  - tracing_stop

  - zombie

  - dead

  - wake_kill

  - waking

  - parked (Linux)

  - idle (Linux, macOS, FreeBSD)

  - locked (FreeBSD)

  - waiting (FreeBSD)

  - suspended (NetBSD)

  See https://psutil.readthedocs.io/en/latest/index.html?highlight=status#process-status-constants

salt.modules.ps.swap_memory()

  Added in version 2014.7.0.

  Return a dict that describes swap memory statistics.

  Note

  This function is only available in psutil version 0.6.0 and above.

  CLI Example:

      salt '*' ps.swap_memory

salt.modules.ps.top(num_processes=5, interval=3)

  Return a list of top CPU consuming processes during the interval. num_processes = return the top N CPU consuming processes interval = the number of seconds to sample CPU usage over

  CLI Examples:

      salt '*' ps.top

      salt '*' ps.top 5 10

salt.modules.ps.total_physical_memory()

  Return the total number of bytes of physical memory.

  CLI Example:

      salt '*' ps.total_physical_memory

salt.modules.ps.virtual_memory()

  Added in version 2014.7.0.

  Return a dict that describes statistics about system memory usage.

  Note

  This function is only available in psutil version 0.6.0 and above.

  CLI Example:

      salt '*' ps.virtual_memory