Jobs

A job is a Salt.Box program object that interacts with the salt-master service in order to create a SaltStack Job, receive Job Returns from minions, and save them in the Salt.Box database.

Creating a job

Creating a job in the minion card

To create a job in a minion card, on the minion page, open the minion card and click the Create Job button located in the upper left part of the card Fig. 1.

Figure 1. Minion card

A dialog box for creating a job will be displayed, and the required values ​​will be set: the targeting type in the Target type field, and the minion ID in the Target field Fig. 2.

Figure 2. Selecting a function for a new job

Creating a task on the tasks page

To create a job on the jobs page, select Jobs in the main menu.
Next, on the jobs page, click the Create Job button located in the upper left part of the page.
A dialog box for creating a job will be displayed, while the default value glob will be specified in the Target type field, and the Target field will be empty.

Selecting a function

In the Function drop-down list, select the function to be called by the job Fig. 2.
The Table 1 shows the list of available functions.

Table 1. Functions of execution modules

Group of functions	Finction	Purpose
cmd	cmd.run	Execute the passed command and return the output as a string
cp	cp.get_dir	Used to recursively copy a directory from the salt master
	cp.get_fil	Download a file from a URL to the Minion cache directory and return the contents of that file. Returns False if Salt was unable to cache a file from a URL
	cp.get_url	Used to get a single file from a URL
disk	disk.blkid	Return block device attributes: UUID, LABEL, etc. This function only works on systems where blkid is available
	disk.fstype	Return the filesystem name of the specified device
	disk.get_fstype_from_path	Return the filesystem type of the underlying device for a specified path
	disk.usage	Return usage information for volumes mounted on this minion
file	file.chgrp	Change the group of a file
	file.chown	Chown a file, pass the file the desired user and group
	file.diskusage	Recursively calculate disk usage of path and return it in bytes
	file.grep	Grep for a string in the specified file
	file.line	Line-focused editing of a file
	file.link	Create a hard link to a file
	file.mkdir	Ensure that a directory is available
	file.move	Move a file or directory
	file.read	Return the content of the file
	file.readdir	Return a list containing the contents of a directory
	file.rmdir	Remove the specified directory. Fails if a directory is not empty
	file.stats	Return a dict containing the stats for a given file
	file.touch	Just like the touch command, create a file if it doesn't exist or simply update the atime and mtime if it already does
grains	grains.append	Append a value to a list in the grains config file. If the grain doesn't exist, the grain key is added and the value is appended to the new grain as a list item
	grains.delkey	Remove a grain completely from the grain system, this will remove the grain key and value
	grains.item	Return one or more grains
	grains.items	Return all of the minion's grains
	grains.set	Set a key to an arbitrary value. It is used like setval but works with nested keys. This function is conservative. It will only overwrite an entry if its value and the given one are not a list or a dict. The force parameter is used to allow overwriting in all cases
mount	mount.active	List the active mounts
	mount.fstab	List the contents of the fstab
	mount.get_device_from_path	Return the underlying device for a specified path
	mount.get_mount_from_path	Return the mount providing a specified path
	mount.mount	Mount a device
	mount.remount	Attempt to remount a device, if the device is not already mounted, mount is called
	mount.swaps	Return a dict containing information on active swap
	mount.umount	Attempt to unmount a device by specifying the directory it is mounted on
network	network.active_tcp	Return a dict containing information on all of the running TCP connections (currently linux and solaris only)
	network.arp	Return the arp table from the minion
	network.connect	Test connectivity to a host using a particular port from the minion
	network.default_route	Return default route(s) from routing table
	network.dig	Performs a DNS lookup with dig
	network.fqdns	Return all known FQDNs for the system by enumerating all interfaces and then trying to reverse resolve them (excluding 'lo' interface)
	network.get_fqdn	Get fully qualified domain name
	network.get_hostname	Get hostname
	network.get_route	Return routing information for given destination ip
	network.hwaddr	Return the hardware address (a.k.a. MAC address) for a given interface
	network.interface	Return the inet address for a given interface
	network.interfaces	Return a dictionary of information about all the interfaces on the minion
	network.ip_addrs	Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is ignored, unless 'include_loopback=True' is indicated. If 'interface' is provided, then only IP addresses from that interface will be returned. Providing a CIDR via 'cidr="10.0.0.0/8"' will return only the addresses which are within that subnet. If 'type' is 'public', then only public addresses will be returned. Ditto for 'type'='private'
	network.mod_hostname	Modify hostname
	network.netstat	Return information on open ports and states
	network.ping	Performs an ICMP ping to a host
	network.routes	Return currently configured routes from routing table
	network.subnets	Returns a list of IPv4 subnets to which the host belongs
	network.traceroute	Performs a traceroute to a 3rd party host
	network.wol	Send Wake On Lan packet to a host
saltutil	saltutil.kill_all_jobs	Sends a kill signal (SIGKILL 9) to all currently running jobs
	saltutil.kill_job	Sends a kill signal (SIGKILL 9) to the named salt job's process
	saltutil.running	Return the data on all running salt processes on the minion
	saltutil.sync_all	Sync down all of the dynamic modules from the file server for a specific environment. This function synchronizes custom modules, states, beacons, grains, returners, output modules, renderers, and utils
	saltutil.sync_grains	Sync grains modules from salt://_grains to the minion
	saltutil.sync_modules	Sync execution modules from salt://_modules to the minion
	saltutil.sync_states	Sync state modules from salt://_states to the minion
state	state.apply	This function will call state.highstate <salt.modules.state.highstate> or state.sls <salt.modules.state.sls> based on the arguments passed to this function
systemd_service	systemd_service.available	Check that the given service is available taking into account template units
	systemd_service.disable	Disable the named service to not start when the system boots
	systemd_service.disabled	Return if the named service is disabled from starting on boot
	systemd_service.enable	Enable the named service to start when the system boots
	systemd_service.get_all	Return a list of all available services
	systemd_service.mask	Mask the specified service with systemd
	systemd_service.masked	Check whether or not a service is masked
	systemd_service.restart	Restart the specified service with systemd
	systemd_service.show	Show properties of one or more units/jobs or the manager
	systemd_service.status	Return the status for a service via systemd. If the name contains globbing, a dict mapping service name to True/False values is returned
	systemd_service.stop	Stop the specified service with systemd
test	test.echo	Return a string - used for testing the connection
	test.ping	Used to make sure the minion is up and responding. Not an ICMP ping
	test.rand_sleep	Sleep for a random number of seconds, used to test long-running commands and minions returning at differing intervals
	test.version	Return the version of salt on the minion
	test.versions	Returns versions of components used by salt
win_service	win_service.available	Check if a service is available on the system
	win_service.delete	Delete the named service
	win_service.disable	Disable the named service to start at boot
	win_service.disabled	Check to see if the named service is disabled to start on boot
	win_service.enable	Enable the named service to start at boot
	win_service.enabled	Check to see if the named service is enabled to start on boot
	win_service.get_all	Return all installed services
	win_service.get_disabled	Return a list of disabled services. Disabled is defined as a service that is marked 'Disabled' or 'Manual'
	win_service.get_enabled	Return a list of enabled services. Enabled is defined as a service that is marked to Auto Start
	win_service.getsid	Return the SID for this windows service
	win_service.info	The name of the service to start
	win_service.missing	The inverse of service.available
	win_service.restart	Restart the named service. This issues a stop command followed by a start
	win_service.start	Start the specified service
	win_service.status	Return the status for a service. If the name contains globbing, a dict mapping service name to True/False values is returned
	win_service.stop	Stop the specified service

Specify arguments if the function accepts them.

Selecting the targeting type and specifying the target

In the Target type drop-down list, select the targeting type Fig. 3.
The targeting type you select determines how the Target field is interpreted.
The targeting types are listed in the Table 2.

Figure 3. Selecting a targeting type for a new job

Table 2. Targeting types

Targeting option	Meaning	Explanation
glob	Bash glob completion	The default matching that Salt utilizes is shell-style globbing around the minion id.
pcre	Perl style regular expression	The target expression will be interpreted as a PCRE regular expression rather than a shell glob.
list	Python list of hosts	The target expression will be interpreted as a comma-delimited list; example: server1.foo.bar,server2.foo.bar,example7.quo.qux
grain	Match based on a grain comparison	The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of '<grain value>:<glob expression>'; example: os:Alt*
grain_pcre	Grain comparison with a regex	The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of '<grain value>:< regular expression>'; example: os:Alt.*
pillar	Pillar data comparison	Instead of using shell globs to evaluate the target, use a pillar value to identify targets. The syntax for the target is the pillar key followed by a glob expression: role:production*
pillar_pcre	Pillar data comparison with a regex	The syntax for the target is the pillar key followed by a pcre expression: role:^(production|server)$
nodegroup	Match on nodegroup	Use a predefined compound target defined in the Salt master configuration file.
range	Use a Range server for matching	Instead of using shell globs to evaluate the target, use a range expression to identify targets. Range expressions look like %cluster. Using the Range option requires that a range server is set up and the location of the range server is referenced in the master configuration file.
compound	Pass a compound match string	Utilize many target definitions to make the call very granular. This option takes a group of targets separated by and or or. The default matcher is a glob as usual. If something other than a glob is used, preface it with the letter denoting the type; example: webserv* and G@os:Debian or E@db* Make sure that the compound target is encapsulated in quotes.
ipcidr	Match based on Subnet (CIDR notation) or IPv4 address	Match based on Subnet (CIDR notation) or IPv4 address.

In the Target field, specify the job target, an expression depending on the selected targeting type.

Confirmation of job creation

Click the Create button Fig. 4.

Figure 4. Job creation dialog

The job will be created, and a window with a job card will be displayed Fig. 5.

info

The job execution starts immediately after creation.

Job card

Figure 5. Job card

The job card consists of two blocks:

• job attributes block Fig. 5 [1]

  the list of job attributes is given in the Table 3

• minion table Fig. 5 [2]

  the tab displays the list of processed targets (minions to which the job was delivered)

The Table 3 describes the job attributes.

Table 3. Job attributes

Attribute	Purpose
Targets	Target of the job
Function	Execution module function
Target Type	Targeting Type
Arguments	Positional Arguments
User	User who created the job
Key-Value arguments	Named Arguments

Job execution

Job execution graph

The Fig. 6 shows the job execution graph.

The conditions for transitions between job statuses are shown in the Table 4.

Figure 6. Job execution graph

Table 4. Transition table of the job execution graph

Edge label	Transition condition
1	Confirmation from salt-master about creation of SaltStack Job was received within 10 minutes from the moment of command creation
2	Confirmation from salt-master about creation of SaltStack Job was not received within 10 minutes from the moment of command creation

Job execution results

Clicking the + icon to the left of the minion entry opens a JSON expression—the response received from the minion Fig. 5 [3].

note

Entries in the minion table appear as responses are received from the minions.

The Table 5 describes the minion table fields.

*Table 5. List of fields of the minion table *

Field	Description
MID	Minion identifier
Success	Job execution status
Return Code	Function return code
Timestamp	Timestamp of the job return