Answer

Some "rules" concepts.

With "rules", there are different concepts of settings to understand :

- default : the default settings are those one considered as best practice recommended by IBM development team, based on their experience. Those default settings are delivered in a "vios_default_rules.xml" file delivered in VIOS install package or modified during update. We can consider those settings as 'factory default' value.

Updating the VIOS to a newer version may cause those default settings to change, in case VIOS rules detects any conflict between new and old settings, the new rule will be ignored so that the current setup remain the same.

- current : those one reflects the current attributes including any customized settings. Those settings are stored in the "/home/padmin/rules/vios_current_rules.xml" file. They are not necessarily the same as the default settings, user is allowed to do some changes in the current rules so that they fit user requirements. We will see later in this document how to to so.
Usually the current settings are the last one that was deployed.

- deployed : this is the settings that are currently applied (i.e. deployed) to the VIOS. There are no real rules file where the deployed value are stored, usually it should be the same as the current. But if there were some manual intervention that changed a settings, it may happen that deployed value (which are the one applied and active on system) are different from the current.

Something to keep in mind with rules is that it does not change individual adapter settings, it works on the predefined attribute from an adapter type. This means that anytime you change a settings using rules it will affect ALL the adapter from this type.

As a consequence, when you deploy a "rules" file, a reboot is required to make the change effective.

Note : The default rules file MUST NEVER be modified. The only rules file(s) we can modify is the current rules file (and if it exists, some personal rules file which we won't address in this technote) BUT this file MUST NOT be modified using a text editor. We’ll see later how to change the rules value.

Note : Before modifying the file, you may want to create a backup of the current rules file : "/home/padmin/rules/vios_current_rules.xml".

How could "rules" help me administering my VIOSes ?

A good starting point is to deploy the IBM recommended settings, and build the current rules file.

Before deploying the default rules, you may want to have a look at default value for each settings :

$ rules -o list -d

Device Type Attribute Value

--------------------------------------------------------------------------------

...

adapter/vdevice/IBM,l-lan min_buf_small 4096

The above indicates the default value (from "vios_default_rules.xml") for min_buf_small for virtual ethernet adapter is 4096.

To deploy the default value (from the rules file provided by IBM) :

$ rules -o deploy -d

A manual post-operation is required for the changes to take effect, please reboot the system.

This will get all the informations from the "vios_default_rules.xml" file and run any required command to change the predefined attribute by adapter type.

Note : After every deploy operation, a message appear to warn you that a reboot is required for the change to take effect. Indeed, the new settings will be active for all devices only after they have been fully reconfigured.

Then create the current rules file :

$ rules -o capture

This command will create the “vios_current_rules.xml” file based on the current VIOS config. This is the file we can modify later to customize our predefined attributes.

For most of the VIOS environment the job is done. After those 2 steps the settings applied to VIOS are the one recommended by IBM development support.

But we can go a bit further...

Checking settings with rules command.

You can check that all settings were correctly applied and are currently deployed by running :

$ rules -o diff -s

This command will go through all settings present in the "vios_current_rules.xml" and check the value currently predefined on the system (ODM), if there's any difference it will be listed as follow :

$ rules -o diff -s

devParam.adapter.vdevice.IBM,l-lan:min_buf_small device=adapter/vdevice/IBM,l-lan 1234 | 2345

In the above output, the first value "1234" is the value currently set in the predefined database.

The second value "2345" is the one set in the "vios_current_rules.xml", which should be the one that was last deployed. As those 2 values are different here, there were probably a manual operation done to change the predefined value outside of rules mechanism.

Something to keep in mind, is that rules command only work with predefined attribute in ODM, this mean that any change done individually on a specific adapter will not be detected as a difference by the rules command.

In the above example the active value for all virtual ethernet adapters will be 1234. But if you ran a chdev command against individual adapter, this adapter will have the setting from chdev command applied and not the predefined value. It means the command above may report no difference at all (the predefined attributes are correctly set as stated in the "vios_current_rules.xml") but some of the adapter might not have those value set.

If you want to check the difference between the default settings and the deployed settings :

$ rules -o diff -s -d

devParam.adapter.vdevice.IBM,l-lan:min_buf_small device=adapter/vdevice/IBM,l-lan 1234 | 4096

As above, the first value is the one currently deployed in the system. This is the value from predefined settings database.

The second value is the one recommended by IBM development team, coming from "vios_default_rules.xml".

You may also want to check the difference between the default settings and the current settings :

$ rules -o diff -d

devParam.adapter.vdevice.IBM,l-lan:min_buf_small device=adapter/vdevice/IBM,l-lan 2345 | 4096

The first value reported is the one coming from "vios_current_rules.xml". If there were no manual operation done after the last deploy this is probably the same as the deployed settings.

The second value is from "vios_default_rules.xml".

Note : This command does not check the settings currently deployed on the VIOS, it will only check the content of the two XML files.

Can i change the settings to be applied by rules command ?

While the default settings are the one recommended by IBM development, there is some case where you may want to change or add the default settings for a specific device. This should be done using the "rules" command.

Note : Do not manually modify any of the XML files containing the rules, it might cause unwanted side effects and generate troubles to your VIOS.

To continue with the previous example, we would like to change the settings for min_buf small of virtual ethernet adapter to something a bit more "smart". Let say for our setup the recommended value of "4096" is a bit high, and we'd like to set it to "2048".

This can be done with the following command :

$ rules -o modify -t adapter/vdevice/IBM,l-lan -a min_buf_small=2048

$ rules -o diff -d

devParam.adapter.vdevice.IBM,l-lan:min_buf_small device=adapter/vdevice/IBM,l-lan 2048 | 4096

The modify gives no output if everything is correct.

We can see, with the "diff" operation, that the "vios_current_rules.xml" file was modified with our new setting value.

At this point the setting changed is not deployed to the system, and we can check this with the "diff" operation :

$ rules -o diff -s

devParam.adapter.vdevice.IBM,l-lan:min_buf_small device=adapter/vdevice/IBM,l-lan 1234 | 2048

The current setting is "2048", but the deployed setting is still the old "1234".

So we need to deploy the current setting to make the change effective in the predefined database :

$ rules -o deploy

A manual post-operation is required for the changes to take effect, please reboot the system.

We put no option after the deploy operation as, by default, it will use the current rules file.

If we check current state

$ rules -o diff -s

$ rules -o diff -s -d

devParam.adapter.vdevice.IBM,l-lan:min_buf_small device=adapter/vdevice/IBM,l-lan 2048 | 4096

We can see the deployed settings are the same as in the current rules file, nevertheless there's a difference with the default rules file.

May i add my own new rules to the file ?

We may also want to add a new settings rule, for instance we want to set min_buf_large to 48 for virtual ethernet adapter.

To check if such settings already exist in the current file :

$ rules -o list | grep "adapter/vdevice/IBM,l-lan"

adapter/vdevice/IBM,l-lan max_buf_tiny 4096

adapter/vdevice/IBM,l-lan min_buf_tiny 4096

adapter/vdevice/IBM,l-lan max_buf_small 4096

adapter/vdevice/IBM,l-lan min_buf_small 2048

There's no such rules, to create one we can run the following :

$ rules -o add -t adapter/vdevice/IBM,l-lan -a min_buf_large=48

$ rules -o list | grep "adapter/vdevice/IBM,l-lan"

adapter/vdevice/IBM,l-lan max_buf_tiny 4096

adapter/vdevice/IBM,l-lan min_buf_tiny 4096

adapter/vdevice/IBM,l-lan max_buf_small 4096

adapter/vdevice/IBM,l-lan min_buf_small 2048

adapter/vdevice/IBM,l-lan min_buf_large 48

Again, the rule was just added to our current rules file, but as we did not deploy yet, this change is not reflected in the predefined database.

Note : If you run the "rules -o diff -s -d" you may expect to see this new rules as a difference compared to default rules file, but there are no way to track the settings deployed that are not present in the default rules file, hence this new rule will not appear as a difference. It will only appear in the difference between the default and the current rules file :

$ rules -o diff -d

devParam.adapter.vdevice.IBM,l-lan:min_buf_small device=adapter/vdevice/IBM,l-lan 2048 | 4096

devParam.adapter.vdevice.IBM,l-lan:min_buf_large device=adapter/vdevice/IBM,l-lan 48 <

The only way to check if this rule has been deployed is with this command run from oem_setup_env :

# lsattr -D -c adapter -s vdevice -t IBM,l-lan -a min_buf_large

min_buf_large 48 Minimum Large Buffers True

Now, what about removing an unwanted rule from the current file ?

Remove the rule we previously added can easily be performed using the following command :

$ rules -o delete -t adapter/vdevice/IBM,l-lan -a min_buf_large

$ rules -o list | grep "adapter/vdevice/IBM,l-lan"

adapter/vdevice/IBM,l-lan max_buf_tiny 4096

adapter/vdevice/IBM,l-lan min_buf_tiny 4096

adapter/vdevice/IBM,l-lan max_buf_small 4096

adapter/vdevice/IBM,l-lan min_buf_small 2048

Unfortunately, as for the "diff" operation, once we removed a rule the deploy operation won't be able to set the predefined value back to its original value. We'll have to do it manually from oem_setup_env.

# chdef | grep min_buf_large

min_buf_large 48 24 adapter/vdevice/IBM,l-lan

The first column is the Attribute name, followed by the "New Default Value" then "Old Default Value" and at last the "Adapter type".

So to "undeploy" the rule we just removed, we have to run the following :

# chdef -a min_buf_large=24 -c adapter -s vdevice -t IBM,l-lan

min_buf_large changed

Note : I would not recommend to use the delete option from rules command, rather use the modify to change the value back to its original value, this way the deploy operation will be able to maintain correct consistency of the profile deployed, and you'll be able to keep track of the value set.