suma Command

Edit online

Purpose

Creates a task to automate the download of Technology Levels (TLs) and Service Packs (SPs) from a fix server.

Syntax

To create, edit, or schedule a Service Update Management Assistant (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 performs the following operations on a SUMA task or policy:
  • Create
  • Edit
  • List
  • Schedule
  • Unschedule
  • Delete
A unique Task ID represents the SUMA task on which the specified operation is performed. The create operation is used to create a new SUMA task and hence a task ID is not specified during the create operation. For the edit operation, if a task ID is not specified, the system creates a new SUMA task and generates a unique task ID for the newly created SUMA task.

Flags

Item Description
-c Lists or edits the SUMA global configuration settings. You can update one or more configuration settings by using the -c flag with a -a flag. When -c flag is used without the -a flag, all SUMA configuration settings are listed.
You can edit the following configuration settings in the Field=Value format by using the -a flag along with the -c flag.
FIXSERVER_PROTOCOL
Specifies that the transfer operation uses https (secure) protocol to communicate with the fix server. The https protocol is the only supported protocol.
DOWNLOAD_PROTOCOL

Specifies whether the transfer operation uses the http protocol or the https protocol to download the filesets. The http protocol uses the multithreaded performance and it uses the download director protocol to download the filesets. The https protocol is single-threaded. The default value is https. The valid values are http and https.

Note: Starting with AIX® 7.3 TL4, the DOWNLOAD_PROTOCOL configuration setting is no longer supported.
DL_TIMEOUT_SEC
Specifies the time in seconds to wait for a response from the fix server during a download operation. Fix server is the internal server. The default value is 180. The valid values are whole numbers greater than zero.
Note: Starting with AIX 7.3 TL4, the DL_TIMEOUT_SEC configuration setting is no longer supported.
HTTP_PROXY and HTTPS_PROXY
Specifies the 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. You can set the http or https proxy service configuration by using the System Management Interface Tool (SMIT). You can specify the server configurations such as IP address, port number, and an optional user ID and password by using the Create/Change Service Configuration menu of the SMIT tool. The suma command no longer supports the settings of the HTTP_PROXY and HTTPS_PROXY parameters. The default value is disabled. The valid value is blank.
Note: Starting with AIX 7.3 TL4, the HTTP_PROXY and HTTPS_PROXY configuration settings are no longer supported.
DIRECT_LAN_CONNECT
Enables or disables the direct LAN connectivity option that the suma command uses to communicate with the fix-central website. The system must have direct internet access to use the direct LAN connectivity option. The default value is yes. The valid values are yes and no.
Note: The DIRECT_LAN_CONNECT setting is introduced in AIX 7.3 TL4.
DIRECT_LAN_PRIORITY
Prioritizes the direct LAN connectivity if the proxy server connectivity is available. The default value is 1. The valid values are whole numbers greater than zero.
Note: The DIRECT_LAN_PRIORITY setting is introduced in AIX 7.3 TL4.
-c (Continued)
PROXY_CONNECT
Enables or disables the proxy server connectivity that the suma command uses to communicate with the fix-central. Configure the proxy server detail through suma command to use this option. The default value is no. The valid values are yes and no.
Note: The PROXY_CONNECT setting is introduced in AIX 7.3 TL4.
PROXY_ADDRESS_1
Specifies the IP address of the primary proxy server. The default value is none.
Note: The PROXY_ADDRESS_1 setting is introduced in AIX 7.3 TL4.
PROXY_PORT_1
Specifies the port number of the primary proxy server. The default value is none.
Note: The PROXY_PORT_1 setting is introduced in AIX 7.3 TL4.
PROXY_USERID_1
Specifies the username of the primary proxy server. The default value is none.
Note: The PROXY_USERID_1 setting is introduced in AIX 7.3 TL4.
PROXY_PASSWORD_1
Adds the password for the primary proxy server. If the password is configured, the password is displayed as an asterisk (*) when you run the suma -c command to list the SUMA task configuration settings.
suma -c
The default value is none.
Note: The PROXY_PASSWORD_1 setting is introduced in AIX 7.3 TL4.
PROXY_PRIORITY_1

Specifies the priority of the primary proxy server. The default value is 2. The valid values are whole numbers greater than zero.

Note: The PROXY_PRIORITY_1 setting is introduced in AIX 7.3 TL4.
PROXY_ADDRESS_2

Specifies the IP address of the secondary proxy server. The default value is none.

Note: The PROXY_ADDRESS_2 setting is introduced in AIX 7.3 TL4.
 
PROXY_PORT_2

Specifies the port number of the secondary proxy server. The default value is none.

Note: The PROXY_PORT_2 setting is introduced in AIX 7.3 TL4.
PROXY_USERID_2

Specifies the username of the secondary proxy server. The default value is none.

Note: The PROXY_USERID_2 setting is introduced in AIX 7.3 TL4.
PROXY_PASSWORD_2

Adds the password of the secondary proxy server. If the password is configured, the password is displayed as an asterisk (*) when you run the suma -c command to list the SUMA task configuration settings. The default value is none.

Note: The PROXY_PASSWORD_2 setting is introduced in AIX 7.3 TL4.
PROXY_PRIORITY_2

Specifies the priority of the secondary proxy server. The default value is 3. The valid values are whole numbers greater than zero.

Note: The PROXY_PRIORITY_2 setting is introduced in AIX 7.3 TL4.
PROXY_ADDRESS_3

Specifies the IP address of the tertiary proxy server. The default value is none.

Note: The PROXY_ADDRESS_3 setting is introduced in AIX 7.3 TL4.
-c (Continued)
PROXY_PORT_3

Specifies the port number of the tertiary proxy server. The default value is none.

Note: The PROXY_PORT_3 setting is introduced in AIX 7.3 TL4.
PROXY_USERID_3

Specifies the username of the tertiary proxy server. The default value is none.

Note: The PROXY_USERID_3 setting is introduced in AIX 7.3 TL4.
PROXY_PASSWORD_3

Adds the password of the tertiary proxy server. If the password is configured, the password is displayed as an asterisk (*) when you run the suma -c command to list the SUMA task configuration settings.

Note: The PROXY_PASSWORD_3 setting is introduced in AIX 7.3 TL4.
PROXY_PRIORITY_3

Specifies the priority of the tertiary proxy server. The default value is 4. The valid values are whole numbers greater than zero.

Note: The PROXY_PRIORITY_3 setting is introduced in AIX 7.3 TL4.
NOTIFY_VERBOSE
Specifies a verbosity level for the information that is sent in an email notification. Applies only to scheduled tasks run from cron command. The default value is LVL_INFO. The valid values are LVL_OFF, LVL_ERROR, LVL_WARNING, LVL_INFO, LVL_VERBOSE, and LVL_DEBUG. For more information, see SCREEN_VERBOSE configuration setting.
LOGFILE_VERBOSE
Specifies a verbosity level for the information that is logged to the /var/adm/ras/suma.log log file.
Note: An LVL_OFF setting logs information to the /var/adm/ras/suma_dl.log downloaded log file. The default value is LVL_VERBOSE. The valid values are LVL_OFF, LVL_ERROR, LVL_WARNING, LVL_INFO, LVL_VERBOSE, and LVL_DEBUG. For more information, see SCREEN_VERBOSE configuration setting.
-c (Continued)
SCREEN_VERBOSE
Specifies a verbosity level to log information to stdout and stderr files. Use this setting when you run the suma command from the command line or from the SMIT interface. This setting is not applicable for scheduled tasks that are run from cron command. The default value is LVL_INFO. The following values are the valid values of this setting:
LVL_OFF
No information is displayed or logged.
LVL_ERROR
Displays error messages and other important messages.
LVL_WARNING
Displays warning messages in addition to the LVL_ERROR messages.
LVL_INFO
Displays informational messages in addition to the LVL_WARNING messages.
LVL_VERBOSE
Displays verbose informational messages in addition to the LVL_INFO messages.
LVL_DEBUG
Displays debug output. This setting is for debugging purposes and must not be used for normal operations.
MAXLOGSIZE_MB
Specifies the maximum size in MB that a log file is allowed to reach. The default value is 1. The valid values are whole numbers greater than zero.
-c (Continued)
REMOVE_CONFLICTING_UPDATES
Specifies whether the lppmgr command must remove conflicting updates that have the same level as base images (lppmgr -u flag) when you run the command during a clean action. The default value is yes. The valid values are yes and no.
REMOVE_DUP_BASE_LEVELS
Specifies whether the lppmgr command must remove duplicate base levels (lppmgr -b flag) when you run the command during a clean action. The default value is yes. The valid values are yes and no.
REMOVE_SUPERSEDE
Specifies whether the lppmgr command must remove superseded fileset updates (lppmgr -x flag) when you run the command during a clean action. The default value is yes. The valid values are yes and no.
TMPDIR
Specifies the directory that stores temporary files. The default value is /var/suma/tmp. The valid value is any directory that currently exists.
SUMA_CHCC_LOG
Enables debug logging and displays all kinds of communication data between the suma command and the cloud or log the communication data in a file. This setting is for debugging purposes and must not be used for normal operations. The default value is NONE. The following values are the valid values of this setting:
NONE
No debug logging.
CONSOLE
Displays debug messages only on the console.
LOGFILE
Creates /var/suma/log/suma_chcc.log log file and writes the debug messages only in the log file.
BOTH
Writes the debug messages both on the console and in the /var/suma/log/suma_chcc.log log file.
Notes:
  1. The SUMA_CHCC_LOG setting is introduced in AIX 7.3 TL2.
  2. By default, the suma command prioritizes direct LAN connectivity over proxy server connectivity, evident from the default priority given to each type.
  3. If DIRECT_LAN_CONNECT is yes, but suma command is not able to connect through direct LAN connectivity, it switches to proxy connectivity in the order of their priorities if PROXY_CONNECT is yes. If it is still not able to connect, the suma command exits with appropriate error message.
  4. Make sure that the same priority value is not assigned for two connectivity types. Otherwise, the suma command considers the first and ignores the second based on their sequence that is specified.
  5. For more information, see Configuring SUMA to use the proxy settings.
-d Deletes the SUMA task that is associated with the specified TaskID and any schedules for this task that were created with the -s flag.
-D Lists or edits the default SUMA task. You can update one or more Fields of the default task to the specified Value by using the -a flag. When used without the -a flag, the default SUMA task is listed.
-l Lists the SUMA tasks. When used without a TaskID, all SUMA tasks are listed. The TaskID is used to specify one or more task IDs to list.
-s CronSched Schedules a SUMA task. If specified when a new task is created, a save is implied (-w flag functions). The CronSched is a list of five space-separated entries (minute, hour, day, month, weekday) contained in quotation marks. The following values are the valid values for these five space-separated entries:
  • Minute ranges from 0 to 59
  • Hours range from 0 to 23
  • Days range from 1 to 31
  • Month ranges from 1 to 12
  • Weekdays range from 0 to 6 (for Sunday - Saturday)

For more information, see crontab command.
-u Unschedules a SUMA task. This flag removes any scheduling information for the specified TaskID.
-w Writes or saves a SUMA task. The task is saved if this flag is used instead of the -s flag, and you can add the scheduling information later. If used with the -x flag, the task is run immediately and is saved.
-x Specifies that a SUMA task must 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. The following values are the supported Fields and Values for the create or edit operation on a SUMA task:
RqType
When suma command is run with an RqType of Latest, the RqType is the only required field. For more information about the default values that are used when suma command is run without any value, see Example 1. Other RqType values (TL, SP, ML, PTF) require specification of Field=Value information.
ML
Specifies a request to download a specific maintenance or TL. For example, 5300-11.
TL
Specifies a request to download a specific TL. For example, 6100-03.
PTF
Specifies a request to download a program temporary fix (PTF). For example, U813941. Only certain PTFs might be downloaded as an individual fileset. For example, PTFs containing bos.rte.install, bos.alt_disk_install.rte, or PTFs that come out in between SPs. Otherwise, the TL or SP must be downloaded.
SP
Specifies a request to download a specific SP. An example is 6100-02-04.
Latest
Specifies a request to download the latest fixes. This RqType value returns the latest SP of the TL specified in FilterML.
-a (Continued)
RqName
Specifies the name of the item requested. For example, 6100-03 or 6100-04-03. The RqName field must be blank when RqType equals Latest.
Repeats
Specifies whether the task is run once and does not remain on the system, repeats the task until the item is located, or repeats the task forever. The Repeats field applies only to scheduled tasks run from cron command 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 is assigned a CronSched with the -s flag. When the RqType equals TL, SP, PTF, or ML, the task is removed if the item is found. When RqType equals Latest, the task is set up to repeat forever.
n
Specifies that the task is run once and does not remain on the system.
-a (Continued)
DisplayName
Indicates the display name for the SUMA task if the SUMA task is available. For example, Download TL 6100-04. This option is used to view existing SUMA tasks in SMIT.
Action
Preview
Specifies that a download preview is performed. No filesets are downloaded.
Download
Specifies that filesets are downloaded into the DLTarget based on the policy.
Clean
Specifies that filesets are downloaded into the DLTarget based on the policy, followed by a clean operation. The lppmgr command is used to clean filesets that are not needed from the DLTarget. The following three configurable lppmgr command flag options are listed in the SUMA global configuration settings:
Metadata
Specifies that metadata files are downloaded instead of fileset updates. The following RqType values are supported:
TL
Downloads metadata for a specific TL.
SP
Downloads metadata for a specific SP.
Latest
Downloads metadata for all SPs for the TL 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 email addresses that are sent a notification after a fileset download or preview. Multiple email addresses must be comma-separated. A notification is sent only if the task is scheduled for execution at a future time (CronSched is specified).
-a (Continued)
FilterDir

Specifies the name of a fix repository directory to filter against so that duplicate fixes are not downloaded. This option allows a directory other than the DLTarget to be filtered against. For example, you might filter against a NIM lpp_source without having to download into this directory. If left blank, the DLTarget is used.

If the value of the FilterDir field ends with /installp/ppc fix repository directory, the suma command filters the fixes within the specified directory.

If the value of the FilterDir field does not end with /installp/ppc fix repository directory, the suma command attempts to search and filter the fixes within the /installp/ppc directory.

If the fix repository directory that is specified by the FilterDir field has the /installp/ppc directory, the filter process is successful.

If the fix repository directory that is specified by the FilterDir field does not have the /installp/ppc directory, the filter process fails.

FilterML
Specifies a TL to filter against. For example, 6100-03. If not specified, the value that is returned by oslevel -r command on the local system is used.
MaxDLSize
Specifies 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 specifies that there is no higher limit on the amount of data to be downloaded.
Extend
Specifying y automatically extends the file system where the DLTarget resides. If n is specified and more space is required for the download, no download occurs.
-a (Continued)
MaxFSSize

Specifies the maximum allowable size to which the DLTarget file system 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 specifies that there is no higher limit on the size of the file system. The file system can be expanded until physical disk space is exhausted if no higher limit is set on the size of the file system.

The actual size of the DLTarget file system after expansion might be slightly larger than the requested size. The expansion process of the DLTarget file system uses the physical partition (PP) size of the volume group (VG). The required file system size is rounded up to the next multiple of a PP when the file system is expanded. The suma command multiplies the total download size of the TLs and SPs by a fudge factor of 1.15 to calculate the required file system memory for the download of the TLs and SPs.

You can calculate the value for the MaxFSize option by using the following formula:

Y = X * 1.15 / (1024 * 1024)

Where Y is the required file system size in MB and X is the total bytes of updates downloaded.

If the available free memory (in MB) in the file system is denoted by Z, and the value of Y is greater than Z, more memory is required in the file system to download the TLs and SPs. The extra memory that is required in the file system can be calculated as the difference of the values of Y and Z in MB. If the total size of the file system is denoted by T (in MB), then the file system is expanded to the value of F, where F is calculated by using the following formula:

F = T + ( Y - Z )

Setting the MaxFSize option to a value greater than the value of F ensures that the file system is expanded to a size that enables the download of fixes to be completed successfully.

Parameters

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

Exit Status

Item Description
0 Indicates that the command is completed successfully.
>0 Indicates that an error occurred.

Examples

  1. To list the SUMA global configuration settings, enter the following command: 
    suma -c
    An output similar to the following sample screen is displayed: 
    FIXSERVER_PROTOCOL=https
DOWNLOAD_PROTOCOL=http
DL_TIMEOUT_SEC=180
DL_RETRY=1
HTTP_PROXY=
HTTPS_PROXY=
DIRECT_LAN_CONNECT=yes
DIRECT_LAN_PRIORITY=1
PROXY_CONNECT=no
PROXY_ADDRESS_1=
PROXY_PORT_1=
PROXY_USERID_1=
PROXY_PASSWORD_1=
PROXY_PRIORITY_1=2
PROXY_ADDRESS_2=
PROXY_PORT_2=
PROXY_USERID_2=
PROXY_PASSWORD_2=
PROXY_PRIORITY_2=3
PROXY_ADDRESS_3=
PROXY_PORT_3=
PROXY_USERID_3=
PROXY_PASSWORD_3=
PROXY_PRIORITY_3=4
SCREEN_VERBOSE=LVL_INFO
NOTIFY_VERBOSE=LVL_INFO
LOGFILE_VERBOSE=LVL_VERBOSE
SUMA_CHCC_LOG=CONSOLE
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, enter the following command: 
    suma -c -a MAXLOGSIZE_MB=2
  3. To list the SUMA task defaults, enter the following command: 
    suma -D
    An output similar to the following sample screen is displayed:
    DisplayName=
Action=Download
RqType=Latest
RqName=
Repeats=y
DLTarget=/usr/sys/inst.images
NotifyEmail=root
FilterDir=/usr/sys/inst.images
FilterML=7300-02
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 AM, enter the following command: 
    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 that some of the SUMA task defaults are used, as displayed by the suma -D command. For example, when the task is default of DLTarget=/usr/sys/inst.images, the installp images are downloaded into the /usr/sys/inst.images/installp/ppc directory.
  5. To view the SUMA scheduling information that is set up when you run the suma -s CronSched command, enter the following command: 
    crontab -l root
  6. To create and schedule a task that checks for a specific TL once a week, for example, every Thursday at 3 AM, downloads it when it becomes available, and sends email notifications to users on a remote system, enter the following command: 
    suma -s "0 3 * * 4" -a RqType=TL -a RqName=6100-04 \
-a NotifyEmail="bob.smith@host2,ann@host2"
    Note: To make a weekly check for a TL, set the Repeats field 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 AM, enter the following command: 
    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 at a specified time, for example, on Monday at 11:00 PM, enter the following command: 
    suma -s "0 23 * * 1" -a Action=Clean -a RqType=ML -a RqName=5300-11 \
-a DLTarget=/lppsrc/5311
    This command also runs the lppmgr command clean operation after the download operation to remove any superseded updates, duplicate base levels, and conflicting updates.
    Note: Before you run a task that specifies Action=Clean, run suma -c command to verify the SUMA global configuration settings that are used when you run lppmgr command. The REMOVE_SUPERSEDE, REMOVE_DUP_BASE_LEVELS, and REMOVE_CONFLICTING_UPDATES fields must be set to yes to run the clean operation.
  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 at a specified time. For example, on Monday at 11:00 PM, filtering against any updates that are already contained in /lppsrc, enter the following command: 
    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 is set up not to repeat.
  10. To run a task that performs a preview to check whether an SP exists on the fix server, and to create and schedule this task to be run later if the SP does not yet exist, enter the following command: 
    suma -x -w -a Action=Preview -a RqType=SP -a RqName=6100-04-02
    Note: A task ID is returned for this newly created task.
  11. To run the newly created task from the example 10 (assume task ID 23 was returned) and attempt to download the SP and save the Action=Download setting for task ID 23, enter the following command: 
    suma -x -w -a Action=Download 23
    Note: As this task is run from the command line, and not scheduled through cron command, the Repeats field is ignored and the task is not deleted whether the SP is found or not.
  12. To schedule task ID 23 to check for a specific SP once a week, for example, every Thursday at 3 AM, and download it when it becomes available, enter the following command: 
    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, enter the following command: 
    suma -u 23
  14. To delete a task that also removes its scheduling information if it exists, enter the following command: 
    suma -d 23
  15. To list multiple SUMA tasks, where 4 and 23 represent task IDs, enter the following command: 
    suma -l 4 23
  16. To list all SUMA tasks, run the following command: 
    suma -l
  17. To create and schedule a task that checks monthly (for example, on the 15th of every month at 2:30 AM) for the latest SP on the specified FilterML attribute, and download any SPs that are not already in the /tmp/latest repository, enter the following command: 
    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 Contains the 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 are downloaded.
/var/spool/cron/crontabs Directory that contains the crontab file for scheduling.