suma Command

Purpose

Creates a task to automate the download of technology levels and service packs from a fix server.

Syntax

To create, edit, or schedule a SUMA task:

suma { { [ -x ] [-w ] } | -s CronSched } [ -a Field=Value ]... [ TaskID ]

To list SUMA tasks:

suma -l [ TaskID ]...

To list or edit the default SUMA task:

suma -D [ -a Field=Value ]...

To list or edit the SUMA global configuration settings:

suma -c [ -a Field=Value ]...

To unschedule a SUMA task:

suma -u TaskID

To delete a SUMA task:

suma -d TaskID

Description

The suma command can be used to perform the following operations on a SUMA task or policy:
  • Create
  • Edit
  • List
  • Schedule
  • Unschedule
  • Delete
The specified operation is performed on the task represented by a unique Task ID. For the create or edit cases on a SUMA task, if the TaskID is not specified, the create operation is assumed, and a unique TaskID is generated. For the -l flag, if TaskID is not specified, a list of all SUMA tasks are displayed. For the -c flag, if the -a flag is not specified, the SUMA global configuration settings are listed.

Flags

Item Description
-c Lists or edits the SUMA global configuration settings. The -a flag allows one or more configuration setting to be updated to the specified value. When used without the -a flag, all SUMA configuration settings are listed.
The configuration settings that can be edited with the -a flag are as follows:
FIXSERVER_PROTOCOL
When communicating with the fix server, this specifies that the transfer utilizes https (secure). The https protocol is the only supported protocol and cannot be changed. Default value: https Allowable value: https
DOWNLOAD_PROTOCOL
When downloading file sets, this specifies whether the transfer utilizes http, or https (secure) transfers. The http protocol takes advantage of multi-threaded performance and utilizes the download director protocol (ddp). The https protocol is single-threaded. Default value: http Allowable values: http, https
DL_TIMEOUT_SEC
Specifies the time in seconds to wait for a response from the fix server during a download operation. Default value: 180 Allowable values: Whole numbers greater than zero.
HTTP_PROXY and HTTPS_PROXY
Proxy server and port to use for the HTTP or HTTPS transfers. The SUMA command shares the proxy connectivity settings with the Electronic Service Agent™. The HTTP or HTTPS proxy service configuration can be set up through the SMIT Create/Change Service Configuration menus (use fastpath smitty srv_conn) that allow the server specifications such as IP address, port number, and an optional user ID and password. SUMA no longer supports the settings of the HTTP_PROXY and HTTPS_PROXY parameters. Default value: blank (disabled) Allowable value: blank
-c (Continued)
SCREEN_VERBOSE
Specifies a verbosity level for logging information to stdout and stderr. Used when the suma command is run from the command line or the SMIT interface. It is not applicable for scheduled tasks run from cron. Default value: LVL_INFO Allowable values:
  • LVL_OFF : No information is displayed or logged.
  • LVL_ERROR : Displays error messages and other highly important messages.
  • LVL_WARNING : Displays warning messages in addition to LVL_ERROR messages.
  • LVL_INFO : Displays informational messages in addition to LVL_WARNING messages.
  • LVL_VERBOSE : Displays verbose informational messages in addition to LVL_INFO messages.
  • LVL_DEBUG : Displays debug output. This setting is for debugging purposes and should not be used for normal operations.
NOTIFY_VERBOSE
Specifies a verbosity level for the information sent in an email notification. Only applies to scheduled tasks run from cron.Default value: LVL_INFO Allowable values: LVL_OFF, LVL_ERROR, LVL_WARNING, LVL_INFO, LVL_VERBOSE, LVL_DEBUG (refer to the SCREEN_VERBOSE setting for value descriptions)
LOGFILE_VERBOSE
Specifies a verbosity level for the information that is logged to the log file (/var/adm/ras/suma.log). Note: An LVL_OFF setting will still log information to the download log file (/var/adm/ras/suma_dl.log).Default value: LVL_VERBOSE Allowable values: LVL_OFF, LVL_ERROR, LVL_WARNING, LVL_INFO, LVL_VERBOSE, LVL_DEBUG (refer to the SCREEN_VERBOSE setting for value descriptions)
MAXLOGSIZE_MB
The maximum size (in MB) that a log file is allowed to reach. Default value: 1 Allowable values: Whole numbers greater than zero.
REMOVE_CONFLICTING_UPDATES
Specifies if lppmgr should remove conflicting updates that have the same level as base images (lppmgr -u flag) when run during a clean action. Default value: yes Allowable values: yes, no
REMOVE_DUP_BASE_LEVELS
Specifies whether lppmgr should remove duplicate base levels (lppmgr -b flag) when run during a clean action. Default value: yes Allowable values: yes, no
-c (Continued)
REMOVE_SUPERSEDE
Specifies whether lppmgr should remove superseded file set updates (lppmgr -x flag) when run during a clean action. Default value: yes Allowable values: yes, no
TMPDIR
Specifies the directory to store temporary files. Default value: /var/suma/tmp Allowable values: Any directory that currently exists.
-d Deletes the SUMA task associated with the given TaskID and any schedules for this task that were created with the -s flag.
-D Lists or edits the default SUMA task. The -a flag allows one or more Fields of the default task to be updated to the specified Value. When used without the -a flag, the default SUMA task will be listed.
-l Lists SUMA tasks. When used without a TaskID, all SUMA tasks will be listed. The TaskID can be used to specify one or more task IDs to list.
-s CronSched Schedules a SUMA task. If specified when a new task is being created, a save is implied (-w flag functionality). The CronSched is a list of five space-separated entries (minute, hour, day, month, weekday) contained in quotation marks. The valid values for these entries are as follows (see the crontab man page for additional details):
  • Minute: 0 - 59
  • Hour: 0 - 23
  • Day: 1 - 31
  • Month: 1 - 12
  • Weekday: 0 - 6 (for Sunday - Saturday)
-u Unschedules a SUMA task. This removes any scheduling information for the specified TaskID.
-w Writes or saves a SUMA task. If used instead of the -s flag, the task is saved, allowing scheduling information to be added later. If used with the -x flag, the task is run immediately and also saved.
-x Specifies that a SUMA task should be run immediately and not scheduled. If used without the -w flag, the task is not saved for future use.
-a Field=Value ... Assigns the specified Value to the specified Field. For the create or edit operation on a SUMA task, the following are the supported Fields and Values.
RqType
When suma is run with an RqType of Latest, the RqType is the only required field. See example 1 for the default values that will be used in this case. Other RqType values (TL, SP, ML, PTF) require specification of additional Field=Value information.
ML
Specifies a request to download a specific maintenance or technology level. An example is 5300-11.
TL
Specifies a request to download a specific technology level. An example is 6100-03.
PTF
Specifies a request to download a PTF. An example is U813941. Only certain PTFs may be downloaded as an individual file set. For example, PTFs containing bos.rte.install, bos.alt_disk_install.rte, or PTFs that come out in between Service Packs. Otherwise, the TL or SP must be downloaded.
SP
Specifies a request to download a specific service pack. An example is 6100-02-04.
Latest
Specifies a request to download the latest fixes. This RqType value returns the latest service pack of the TL specified in FilterML.
-a (Continued)
RqName
The specific name of the item requested (for example, 6100-03 or 6100-04-03). The RqName field should be blank when RqType equals Latest.
Repeats
Specifies whether the task is executed once and does not remain on the system, repeats until the item is found, or repeats forever. The Repeats field only applies to scheduled tasks run from cron that have an Action of Download, Clean, or Metadata. If run from the command line or if Action is Preview, this field is ignored, and no task is removed.
y
Sets up a repeating task, and requires that the task has been assigned a CronSched with the -s flag. When the RqType equals TL, SP, PTF, or ML, the task is removed as soon as the item is found. When RqType equals Latest, the task is set up to repeat forever.
n
Specifies that the task is executed once and does not remain on the system.
-a (Continued)
DisplayName
Indicates the display name for this SUMA task (for example, Download Latest for 6100-04"). This is used when viewing existing SUMA tasks in SMIT.
Action
Preview
Specifies that a download preview is performed. No file sets are downloaded.
Download
Specifies that file sets are downloaded into the DLTarget based on the policy.
Clean
Specifies that file sets are downloaded into the DLTarget based on the policy, followed by a clean operation. The lppmgr command is used to clean file sets that are not needed from the DLTarget. The three configurable lppmgr flag options listed in the SUMA global configuration settings are:
Metadata
Specifies that metadata files are downloaded instead of file set updates. The following RqType values are supported:
TL
Downloads metadata for a specific technology level.
SP
Downloads metadata for a specific service pack.
Latest
Downloads metadata for all service packs for the technology level that is specified for the FilterML flag.
DLTarget
Contains the directory location where the downloaded files are stored. If this field is not specified, it is given the value /usr/sys/inst.images and the files are stored in a directory based on the image type; for example /usr/sys/inst.images/installp/ppc or /usr/sys/inst.images/RPMS/ppc.
NotifyEmail
Contains one or more e-mail addresses (multiple addresses should be comma-separated) that are sent a notification e-mail after a file set download or preview. A notification is sent only if the task is scheduled for execution at a future time (CronSched has been specified).
-a (Continued)
FilterDir
Specifies the name of a fix repository directory to filter against so that duplicate fixes are not downloaded. This allows a directory other than the DLTarget to be filtered against. For example, you may filter against a NIM lpp_source without having to download into this directory. If left blank, the DLTarget is used.
FilterML
Specifies a technology level to filter against; for example, 6100-03. If not specified, the value returned by oslevel -r on the local system is used.
MaxDLSize
The maximum allowable amount of data to be downloaded by any single policy execution, in MB. If it is determined that the download operation exceeds this size, no download occurs. A value of "unlimited" or -1 can be specified to indicate no upper limit on the amount of data to be downloaded.
Extend
Specifying y automatically extends the filesystem where the DLTarget resides. If n is specified and additional space is required for the download, no download occurs.
MaxFSSize
The maximum allowable size to which the DLTarget filesystem can be extended, in MB. If it is determined that the download operation exceeds this limit, no download occurs. A value of "unlimited" or -1 can be specified to indicate no upper limit on the size of the filesystem (that is, the filesystem can be expanded until physical disk space is exhausted).

Parameters

Item Description
TaskID Specifies a unique numeric identifier that is associated with a task. This is assigned when a task is created.

Exit Status

Item Description
0 The command completed successfully.
>0 An error occurred.

Examples

  1. To list the SUMA global configuration settings, type the following: 
    suma -c
    Output similar to the following is displayed: 
    FIXSERVER_PROTOCOL=https
DOWNLOAD_PROTOCOL=http
DL_TIMEOUT_SEC=180
DL_RETRY=1
HTTP_PROXY=
HTTPS_PROXY=
SCREEN_VERBOSE=LVL_INFO
NOTIFY_VERBOSE=LVL_INFO
LOGFILE_VERBOSE=LVL_VERBOSE
MAXLOGSIZE_MB=1
REMOVE_CONFLICTING_UPDATES=yes
REMOVE_DUP_BASE_LEVELS=yes
REMOVE_SUPERSEDE=yes
TMPDIR=/var/suma/tmp
  2. To edit the SUMA global configuration setting to change the maximum log file size to 2 MB, type the following: 
    suma -c -a MAXLOGSIZE_MB=2
  3. To list the SUMA task defaults, type the following: 
    suma -D
    Output similar to the following is displayed: 
    DisplayName=
Action=Download
RqType=Latest
RqName=
Repeats=y
DLTarget=/usr/sys/inst.images
NotifyEmail=root
FilterDir=/usr/sys/inst.images
FilterML=
MaxDLSize=-1
Extend=y
MaxFSSize=-1
  4. To create and schedule a task that downloads the latest fixes monthly (for example, on the 15th of every month at 2:30 a.m.), type the following: 
    suma -s "30 2 15 * *" -a RqType=Latest \
-a DisplayName="Latest fixes - 15th Monthly"
    Note: A task ID is returned for this newly created task. This example assumes some of the SUMA task defaults, as displayed in the suma -D example, are utilized. For example, when the task default of DLTarget=/usr/sys/inst.images, the installp images are downloaded into the /usr/sys/inst.images/installp/ppc directory.
  5. To view SUMA scheduling information that has been set up by running a suma -s CronSched command, type the following: 
    crontab -l root
  6. To create and schedule a task that checks for a specific technology level once a week (for example, every Thursday at 3 a.m.), downloads it when it becomes available, and sends e-mail notifications to users on a remote system, type the following: 
    suma -s "0 3 * * 4" -a RqType=TL -a RqName=6100-03 \
-a NotifyEmail="bob.smith@host2,ann@host2"
    Note: For this task to make a weekly check for a TL, the Repeats field needs to be set to y. In this case, after the TL is found, the task is deleted. If Repeats=n, only a single check occurs before deleting the task.
  7. To create and schedule a task that checks for critical fixes monthly (for example, on the 20th of every month at 4:30 a.m.), type the following: 
    suma -s "30 4 20 * *" -a RqType=Latest -a RqName= \
-a RqLevel=latest -a Repeats=y
    Note: By setting Repeats=y, this task 'repeats forever' and is not deleted after a successful download.
  8. To create and schedule a task that downloads the entire AIX® Version 7.1 with the 5300-11 Recommended Maintenance package into the /lppsrc/5311 directory on Monday at 11:00 p.m., and runs an lppmgr clean operation after the download operation to remove any superseded updates, duplicate base levels, and conflicting updates, type the following: 
    suma -s "0 23 * * 1" -a Action=Clean -a RqType=ML -a RqName=5300-11 \
-a DLTarget=/lppsrc/5311
    Note: Prior to running a task that specifies Action=Clean, you can run suma -c to verify the SUMA global configuration settings that are used when you run lppmgr command. In this case, having REMOVE_SUPERSEDE, REMOVE_DUP_BASE_LEVELS, and REMOVE_CONFLICTING_UPDATES all set to yes results in the action previously described.
  9. To create and schedule a task that downloads the entire AIX Version 7.1 with the 5300-11 Recommended Maintenance package into the /tmp/lppsrc/5311 directory on Monday at 11:00 p.m., filtering against any updates already contained in /lppsrc, type the following: 
    suma -s "0 23 * * 1" -a RqType=ML -a RqName=5300-11 \
-a DLTarget=/tmp/lppsrc/5311 -a FilterDir=/lppsrc -a FilterSysFile=/dev/null
    Note: After the task is successfully completed, the task is removed, because RqType=TL is a 'repeat until found' task. However, if Repeats=n, only a single check for the 5300-03 TL is made, and if the TL is not found on the fix server, the task is deleted because it has been set up not to repeat.
  10. To immediately execute a task that performs a preview to check if an SP exists on the fix server, and to create and save this task for later scheduling if the SP does not yet exist, type the following: 
    suma -x -w -a Action=Preview -a RqType=SP -a RqName=6100-04-03
    Note: A task ID is returned for this newly created task.
  11. To immediately execute the newly created task from the above example (assume task ID 23 was returned) and attempt to download the SP and save the Action=Download setting for task ID 23, type the following: 
    suma -x -w -a Action=Download 23
    Note: Because this task is being run from the command line, and not scheduled through cron, the Repeats field are ignored and this task is not deleted regardless of whether the SP is found.
  12. To schedule task ID 23 to repeatedly check for a specific SP once a week (for example, every Thursday at 3 a.m.), and download it when it becomes available, type the following: 
    suma -s "0 3 * * 4" -a Repeats=y 23
    Note: This task is deleted when the SP is found.
  13. To unschedule a task that removes its scheduling information from the crontab file in the /var/spool/cron/crontabs directory, type the following: 
    suma -u 23
  14. To delete a task that also removes its scheduling information if it exists, type the following: 
    suma -d 23
  15. To list multiple SUMA tasks, where 4 and 23 represent task IDs, type the following: 
    suma -l 4 23
  16. To list all SUMA tasks, type the following: 
    suma -l
  17. To create and schedule a task that checks monthly (for example, on the 15th of every month at 2:30 a.m.) for the latest service pack on the specified FilterML, and download any that are not already in the /tmp/latest repository, type the following: 
    suma -s "30 2 15 * *" -a RqType=Latest -a FilterML=6100-02 \
-a DLTarget=/tmp/latest -a FilterDir=/tmp/latest
    Note: A task ID is returned for this newly created task.

Location

/usr/suma/bin/suma

Files

Item Description
/usr/suma/bin/suma Contains the suma command.
/usr/sbin/suma Link to /usr/suma/bin/suma.
/var/adm/ras/suma.log Contains detailed results from running the suma command.
/var/adm/ras/suma_dl.log Contains a list of files that have been downloaded.
/var/spool/cron/crontabs Directory that contains the crontab file for scheduling.