rules command

Purpose

Manages and deploys device setting rules on the Virtual I/O Server (VIOS).

Syntax

rules -o operation [ -l deviceInstanceName | -t class/subclass/type ][ -a Attribute=Value ] [-d] [-n] [-s] [ -f RulesFile ] [-F] [-h]

Description

The rules command is used to capture, deploy, change, compare, and view VIOS rules. It leverages AIX® Run Time Expert Solution (ARTEX) technology. VIOS provides predefined default rules that contain the critical rules for VIOS device configuration that are suggested for VIOS best practice. You can use the rules command to manage device settings rules on VIOS.

Parameters

Parameter name	Description
-o operation	capture Captures the current system configuration on the VIOS. If the current rules exist, the new captured system configuration overwrites the existing ones. Otherwise, the factory default rules are used as a template to capture current system settings.
	deploy Applies the suggested factory default rules for best practice, or current rules on the VIOS. The parameter not only deploys the new settings to the device type but also makes changes to device instances. If no current rules exist, the parameter creates a new rules file based on the current system settings, and informs you to modify the rules and deploy again. The new setting does not take effect until system reboot.
	import Imports a user-specified rules file to VIOS current rules. The user-specified rules are primary if the same rules exist in the current rules file during a merge operation. If there is no existing current rules file, a current rules file is created based on default rules. If a rule or device is a not supported by the AIX ARTEX catalog, the import operation fails and informs you to remove the invalid rule and try again. If the changed value is lower than the current default in ODM, a warning is displayed for your awareness. However, the import operation is allowed to continue and complete. To control rules compatibility, by default, the `ioslevel` rule is compared with current rules and the user-specified rules. If the user-specified `ioslevel` is lower than the current rules or missing, the operation stops. You must use the -F flag to force the import operation to continue without any checking.
	list Lists and views the rules file contents or the system configuration based on the rules template. The first column of the output is `class/subclass/type`, the second is `attribute`, and the third is `value`.
	diff Lists the mismatch devices and attributes, and quantifies the difference numerically, if you specify the -n flag.
	add Adds a new rule to the VIOS current rules or a user-specified rule file, based on device instance name or device unique type. If the rule already exists, it returns an error. However, the device instance or device type must be supported by the existing AIX ARTEX catalog. Otherwise, the command fails. Note: The command `rules -o add -l hdisk0 -a reserve_policy=no_reserve` is used to add a rule for disk/fcp/mpioosdisk instead of for hdisk0 only. It is an easier and more convenient version call as compared to `rules -o add -t class/subclass/type -a reserve_policy=no_reserve` if you do not have the ODM information.
	modify You can modify a rule from the current rules or user-specified rules file, based on device type or device instance. If the rule that you try to modify does not exist, an error message is displayed to ask you to add a rule instead of trying to modify a rule. Note: See the note in the add operation for device instance and type usage.
	delete Deletes a rule from current rules or a user-specified file. If a rule that needs to be deleted does not exist, an error message is displayed. You cannot remove the rules contained in default rules from the current rules or the user-specified rules file. Note: See the note in the add operation for device instance and type usage.
-l deviceInstanceName	You can use the device instance name to search for the device type (class/subclass/type) in ODM. This ensures that you can create a new rule without having knowledge about the ODM information. The -l flag is exclusive with the -t flag.
-t class/subclass/type	You can use a tag to specify the device class, subclass, and type of the device. The -t flag is exclusive with the -l flag.
-a attribute=value	Attribute and value are a pair setting for a device type. This parameter is required for the add or modify rule for a particular attribute.
-d	Sets the default rules of the system.
-n	When used with the `rules -o diff` command, it shows the number of differences.
-s	When used with the `rules -o diff` command, it to shows and lists current system settings.
-f rulesFile	Used for a user-specified rules file.
-F	When used with the `rules -o import` command, it forces the import operation to continue even if non-fatal errors are encountered.
-h	Displays the usage.

Exit Status

This command returns the following exit values:

Return code	Description
0	Successful completion.
>0	An error occurred.

Files

Item	Description
/usr/sbin/rules	Contains the rules command.

Security

The rules command is supported by RBAC and can be accessed by the padmin and root users.

Examples

To add new rules, type the following command:

rules -o add -t disk/vscsi/cvdisk -a queue_depth=8

To add reserve_policy rules to current rules for a device type whose instance is hdisk0, type the following command:
```
rules -o add -l hdisk0 -a reserve_policy=no_reserve
```
To add serve_policy rules to current rules for a device type disk/fcp/mpioosdisk, type the following command:
```
rules -o add -t disk/fcp/mpioosdisk -a reserve_policy=no_reserve
```
To add service_policy rules to a user-specified rules file for device type whose instance is hdisk0, type the following command:
```
rules -o add -l hdisk0 -a reserve_policy=no_reserve -f/tmp/rules.xml
```

To delete rules, type the following command:

rules -o delete -t disk/vscsi/cvdisk -a queue_depth

To delete reserve_policy from current rules for disk/fcp/mpioapdisk device type, type the following command:
```
rules -o delete -t disk/fcp/mpioapdisk -a reserve_policy
```
To delete reserve_policy from current rules for hdisk0 device type, type the following command:
```
rules -o delete -l hdisk0 -a reserve_policy
```
To delete reserve_policy from /tmp/rules.xml rules file for hdisk0 device type, type the following command:
```
rules -o delete -l hdisk0 -a  reserve_policy -f /tmp/rules.xml
```

To modify existing rules, type the following command:

rules -o modify -t adapter/pciex/df1000fe -a num_cmd_elems=2048

To modify reserve_policy rules from the current rules file for disk/fcp/mpioapdisk device type, type the following command:
```
rules -o modify -t disk/fcp/mpioapdisk -a reserve_policy=no_reserve
```
To modify reserve_policy rules from the current rules file for hdisk0 device type, type the following command:
```
rules -o modify -l hdisk0 -a reserve_policy=no_reserve
```
To modify reserve_policy rules from /tmp/rules.xml rules file for hdisk0 device type, type the following command:
```
rules -o modify -l hdisk0 -a reserve_policy=no_reserve -f /tmp/rules.xml
```
To list and view the default rules, type the following command:
```
rules -o list -d
```
To list and view the current rules, type the following command:
```
rules -o list
```
To list and view the current system setting, type the following command:
```
rules -o list -s
```
To list and view the rules contents from a user-specified file, type the following command:
```
rules -o list -f user_rules.xml
```
To list the mismatch devices and attributes between VIOS system settings and current rules, type the following command:
```
rules -o diff -s
```
To list the mismatch devices and attributes between VIOS system settings and default rules, type the following command:
```
rules -o diff -s -d
```
To list the mismatch devices and attributes between current rules and factory default rules, type the following command:
```
rules -o diff -d
```
To list the mismatch devices and attributes between current rules and user_rules.xml file, type the following command:
```
rules -o diff -f user_rules.xml
```
To list the mismatch devices and attributes between two rules files, type the following command:
```
rules -o diff -f rules1.xml rules2.xml
```
To find the mismatch number between two files, type the following command:
```
rules -o diff -n -f rules1.xml rules2.xml
```

To list rules in the system, type the following command:

rules -o list -s

The system displays the following output:

disk/fcp/mpioosdisk            reserve_policy       no_reserve
disk/fcp/mpioapdisk            reserve_policy       single_path
disk/fcp/nonmpiodisk           reserve_policy       no_reserve
disk/fcp/aixmpiods8k           reserve_policy       no_reserve
disk/sas/mpioapdisk            reserve_policy       no_reserve
disk/sas/mpioosdisk            reserve_policy       no_reserve
disk/sas/scsd                  reserve_policy       no_reserve
disk/sas/sisarray              reserve_policy       no_reserve
disk/vscsi/cvdisk              reserve_policy       no_reserve

To capture VIOS current system settings and save it to the current rules file, type the following command:
```
rules -o capture
      
```
To deploy VIOS recommended default rules, type the following command:
```
rules -o deploy -d
```
To deploy VIOS current rules, type the following command:
```
rules -o deploy
```
To import a user-specified rules file to current rules, type the following command:
```
rules -o import -f user_rules.xml
```
To import user-specified rules contained in the file user_rules.xml to current rules and to ignore the ioslevel incompatibility, type the following command:
```
rules -o import -f user_rulex.xml -F
```
To display the usage of the rules command, type the following command:
```
rules -h
```