swjob(1M)

NAME

swjob, sd — display and monitor job information and create and remove jobs; invoke graphical user interface to display and monitor job information and create and remove jobs; respectively

SYNOPSIS

swjob [-i] [-R] [-u] [-v] [-a attribute] [-C session_file] [-f jobid_file] [-S session_file] [-t target_file] [-x option=value] [-X option_file] [jobid(s)] [@ target_selections]

sd [XToolkit Options] [-x option=value] [-X option_file]

Remarks

The sd command invokes an interactive interface to the same functionality that swjob provides. See Interactive Operation below for more details.
This command supports operation on remote systems. See Remote Operation below for details.
For an overview of all SD commands, see the sd(5) man page by typing man 5 sd on the command line.

DESCRIPTION

The swjob command displays job information and removes jobs. It supports these features:

Display the current install jobs, copy jobs, and other SD jobs initiated by the SD commands.
Specify a specific job to list or remove.
Display the command logfile for a specific job.
Display the target logfile for a specific target.

Remote Operation

You can enable Software Distributor (SD) to manage software on remote systems. To let the root user from a central SD controller (also called the central management server or manager node) perform operations on a remote target (also called the host or agent):

1)

Set up the root, host, and template Access Control Lists (ACLs) on the remote machines to permit root access from the controller system. To do this, run the following command on each remote system:

/usr/lib/sw/mx/setaccess controller

NOTES:

controller is the name of the central management server.
If remote system is 11.00, make sure SD patch PHCO_22526 or a superseding patch is installed on remote system before running setaccess.
If remote system is older than 11.00 or for some other reason does not have setaccess in place, copy setaccess script from an 11.11 or higher system to the remote system.

2)

swinstall, swcopy, and swremove have enhanced GUI interfaces for remote operations. Enable the enhanced GUIs by creating the .sdkey file on the controller. Use this command:

touch /var/adm/sw/.sdkey

NOTE: You can also set up remote access by using swacl directly on the remote machines to grant root or non-root access to users from the controller system.

Interactive Operations

The sd command is an interactive interface for monitoring and scheduling software jobs. It provides the same functionality as the swjob command. You can also use sd to invoke the swinstall, copy, and swremove GUIs.

If you have enabled SD's remote operations features, swinstall, swcopy, and swremove provide enhanced GUIs to support operations on remote targets. See Remote Operation above for details about enabling remote operations and the enhanced GUIs.

Options

When no options or operands are specified, swjob lists the jobs that exist on the local host. These jobs may be pending, active, in the background or completed. The swjob command supports the following options:

XToolKit Options

The sd command supports a subset of the standard XToolkit options to control the appearance of the system GUI. The supported options are: -bg, -background, -fg, -foreground, -display, -name, -xrm, and -synchronous. See the X(1) man page by typing man X for a definition of these options.

-i

Runs the command in interactive mode (invokes the GUI.) (Using this option is an alias for the sd command.) See the Interactive Operation and Remote Operation headings above for details.

-R

Applies to target lists as a shorthand for @ *::*.

-u

Causes swjob to remove the specified job(s).

-v

Causes swjob to list all available attributes, one per line. The option applies only to the default list.

-a attribute

Each job has its own set of attributes. These attributes include such things as job title, schedule date, or results. The -a option selects a specific attribute to display. You can specify multiple -a options to display multiple attributes. See also sd(4) for details on these attributes. This option applies only to the default list.

The logfiles summarizing a job or detailing target actions can be displayed using -a log, if -a log is specified and no other attribute is specified (i.e. no other attribute may be specified).

-C session_file

Save the current options and operands to session_file. You can enter a relative or absolute path with the file name. The default directory for session files is $HOME/.sw/sessions/. You can recall a session file with the -S option.

-f jobid_file

Read the list of jobids from jobid_file instead of (or in addition to) the command line.

-t target_file

Read the list of target_selections from target_file instead of (or in addition to) the command line.

-x option=value

Set the session option to value and override the default value (or a value in an alternate option_file specified with the -X option). Multiple -x options can be specified.

-S session_file

Execute swjob based on the options and operands saved from a previous session, as defined in session_file. You can save session information to a file with the -C option.

-X option_file

Read the session options and behaviors from option_file.

Operands

The swjob command supports two types of operands: jobid followed by target selections. These operands are separated by the "at" (@) character. This syntax implies that the command operates on "jobid at targets".

jobid The swjob command supports the following syntax for each job id:
jobid
target selections The swjob command supports the following syntax for each target selection:
[host][:][directory]

EXTERNAL INFLUENCES

Default Options

In addition to the standard options, several SD behaviors and policy options can be changed by editing the default values found in:

/var/adm/sw/defaults: the system-wide default values.
$HOME/.swdefaults: the user-specific default values.

Values must be specified in the defaults file using this syntax:

[command_name.]option=value 

The optional command_name prefix denotes one of the SD commands. Using the prefix limits the change in the default value to that command. If you leave the prefix off, the change applies to all commands.

You can also override default values from the command line with the -x or -X options:

command -x option=value

command -X option_file

The following section lists all of the keywords supported by the swjob command. If a default value exists, it is listed after the =.

The policy options that apply to swjob are:

admin_directory=/var/adm/sw (for normal mode)

admin_directory=/var/home/LOGNAME/sw (for nonprivileged mode)

The location for SD logfiles and the default parent directory for the installed software catalog. The default value is /var/adm/sw for normal SD operations. When SD operates in nonprivileged mode (that is, when the run_as_superuser default option is set to true):

The default value is forced to /var/home/LOGNAME/sw.
The path element LOGNAME is replaced with the name of the invoking user, which SD reads from the system password file.
If you set the value of this option to HOME/path, SD replaces HOME with the invoking user's home directory (from the system password file) and resolves path relative to that directory. For example, HOME/my_admin resolves to the my_admin directory in your home directory.

SD's nonprivileged mode is intended only for managing applications that are specially designed and packaged. This mode cannot be used to manage the HP-UX operating system or patches to it. For a full explanation of nonprivileged SD, see the Software Distributor Administration Guide, available at the http://docs.hp.com web site.

Session File

Each invocation of the swjob command defines a job display session. The invocation options, source information, software selections, and target hosts are saved before the installation or copy task actually commences. This lets you re-execute the command even if the session ends before proper completion.

Each session is automatically saved to the file $HOME/.sw/sessions/swjob.last. This file is overwritten by each invocation of swjob.

You can also save session information to a specific file by executing swjob with the -C session__file option.

A session file uses the same syntax as the defaults files. You can specify an absolute path for the session file. If you do not specify a directory, the default location for a session file is HOME/.sw/sessions/.

To re-execute a session file, specify the session file as the argument for the -S session__file option of swjob.

Note that when you re-execute a session file, the values in the session file take precedence over values in the system defaults file. Likewise, any command line options or parameters that you specify when you invoke swjob take precedence over the values in the session file.

Environment Variables

SD programs are affected by external environment variables.

SD programs that execute control scripts set environment variables for use by the control scripts. swjob does not set environmental variables, but it uses them.

Environment variables that affect the SD commands:

LANG

Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of C is used. See the lang(5) man page by typing man 5 lang for more information.

NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, /etc/rc.config.d/LANG. For example, /etc/rc.config.d/LANG, must be set to LANG=ja_JP.SJIS or LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese.

LC_ALL

Determines the locale to be used to override any values for locale categories specified by the settings of LANG or any environment variables beginning with LC_.

LC_CTYPE

Determines the interpretation of sequences of bytes of text data as characters (e.g., single-versus multibyte characters in values for vendor-defined attributes).

LC_MESSAGES

Determines the language in which messages should be written.

LC_TIME

Determines the format of dates (create_date and mod_date) when displayed by swlist. Used by all utilities when displaying dates and times in stdout, stderr, and logging.

TZ

Determines the time zone for use when displaying dates and times.

Signals

The swjob command catches the signals SIGQUIT and SIGINT. If these signals are received, swjob prints a message, sends a Remote Procedure Call (RPC) to the daemons to wrap up, and then exits.

Each agent will complete the list task before it wraps up.

OPERATION

Different views of the job information are available. The types of listings that can be selected are given below.

Default Listing
Target Listing
Logfile Listing

Default Listing

If swjob is invoked with no options or operands, it lists all jobs that are on the local host. This listing contains one line for each job. The line includes the job tag attribute and all other attributes selected via the one_liner option.

Listing jobs on a remote controller is not supported. If a jobid is given, information for only that job is displayed.

Status Listing

If a -R or @ target_specification is given, the targets for that job and their status are displayed. By default the status information includes Type, State, Progress and Results.

Logfile Listing

One of the attributes "log" encompasses a variety of logfile types. The type of logfile returned when the -a log attribute is given depends on the operands given. The types of logfiles:

No target_selections: Show the controller logfile (default).
@ target: Show the agent logfile.

RETURN VALUES

The swjob command returns:

0: The job information was successfully listed or the job was successfully removed.
1: The list /remove operation failed for all jobids.
2: The list /remove operation failed for some jobids.

DIAGNOSTICS

The swjob command writes to stdout, stderr, and to the agent logfile.

Standard Output

All listings are printed to stdout.

Standard Error

The swjob command writes messages for all WARNING and ERROR conditions to stderr.

Logging

The swjob command does not log summary events. It logs events about each read task to the swagent logfile associated with each target_selection.

swagentd Disabled

If the swagentd daemon has been disabled on the host, it can be enabled by the host's system administrator by setting the SW_ENABLE_SWAGENTD entry in /etc/rc.config.d/swconfig to 1 and executing /usr/sbin/swagentd -r.

EXAMPLES

To list all of the jobs that exist on the local host:

swjob 

To show the scheduled date for job hostA-0001:

swjob -a schedule hostA-0001 

For job hostA-0001 list the targets and their status:

swjob -R hostA-0001 
or
swjob hostA-0001 @ *::* 

For job hostA-0001 list the controller log:

swjob -a log hostA-0001 

For job hostA-0001 list the targetA agent log:

swjob -a log targetA-0001 @ targetA 

FILES

$HOME/.swdefaults: Contains the user-specific default values for some or all SD options.
/usr/lib/sw/sys.defaults: Contains the master list of current SD options (with their default values).
/var/adm/sw/: The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles.
/var/adm/sw/defaults: Contains the active system-wide default values for some or all SD options.
/var/adm/sw/queue/: The directory which contains the information about all active and complete install jobs, copy jobs, and other jobs initiated by the SD commands.

AUTHOR

swjob was developed by the Hewlett-Packard Company.