pksctl Command

Edit online

Purpose

Performs administrative operations on the user-space Platform keystore (PKS) framework.

Syntax

To add a new consumer 
pksctl register -name <consumer> [-password-file <file>] [-min-quota <size>] [-max-quota size>] [-type {multi | single}]
To remove an existing consumer
pksctl deregister -name <consumer> -force
To decrease the maximum quota for a specific consumer
pksctl quota-shrink -name <name> -shrink-max <new_size>
To query statistics about framework usage, or a registered consumer if specified 
pksctl stats [-name <consumer>]
To increase the minimum quota, maximum quota, or both for a specific user
pksctl quota-expand -name <consumer> [-expand-min <new_size>] [-expand-max <new_size>]
To modify the default quota values for consumers to be registered in future
pksctl set-default [-default-min <new_size>] [-default-max <new_size>] [-default-split <percentage>]
To clear out objects that are leftover from prior installs
pksctl purge {-dry-run | -clear}

Description

The pksctl command is used to perform administrative operations that relate to the PKS framework at the user-space. The administrator can perform the following operations:
  • Register or unregister a consumer.
  • Query metrics about usage.
  • Modify specific and default usage limits.

Special Role Based Access Control (RBAC) privileges are assigned to the pksctl command. The RBAC privileges allow the pksctl command to perform certain privileged operations.

Notes:
  • A unique name must be provided for every consumer during the register operation. If you try to register two or more consumers with the same name, only the first registration request is processed. Any subsequent request to register consumers with the same name is rejected. Once a consumer is registered with a name, the name remains same for that consumer.
  • To unregister a consumer, you must delete all the objects that are stored in the nonvolatile random access memory (NVRAM) for the specified consumer. The deregister operation is rejected with an EAGAIN error code if there are objects stored in the NVRAM that are mapped to the specified consumer.
  • The size of the minimum quota for a specific consumer cannot be reduced once the user is registered. However, the default size of the minimum quota can be changed at any time. The size of the minimum quota is specified when the consumer is registered.

Flags

Table 1. Flags
Item Description
-clear

Performs the purge operation. The -clear flag removes all the objects that are not mapped to a valid registered consumer.

-default-max new_size

 Sets the default value of the maximum quota for the consumers that are to be registered in the future. All the existing consumers are unaffected.
Note: You can use the -expand-max and -shrink-max flags to modify the default maximum quota for existing consumers.
-default-min new_size

 Sets the default value of the minimum quota for the consumers that are to be registered in the future. All the existing consumers are unaffected.
Note: You can use the -expand-min and -shrink-min flags to modify the default minimum quota for existing consumers.
-default-split percentage

Decides the NVRAM space, in percentage, that must be reserved for use by the PKS framework. The percentage variable value must be a whole number. The valid values are in the range 40-100.

Note: The total space that is specified by the -default-split flag denotes the space that the consumers can use in the kernel address space. Therefore, the value that is reserved for the user-space is calculated as the difference between 100 and the percentage variable value.
-dry-run Lists all the objects that are stored in the NVRAM, but are not mapped to a registered consumer. The -dry-run flag and the -clear flag cannot be used together.
-expand-max new_size Increases the maximum quota size of a registered consumer to the value specified by the new_size variable. The consumer for whom the maximum quota size is increased, is specified by the -name parameter.
-expand-min new_size Increases the minimum quota size of a registered consumer to the value specified by the new_size variable. The consumer for whom the minimum quota size is increased, is specified by the -name parameter.
-force Specifies the intent to remove an eligible consumer. The -force flag is a mandatory flag for the deregister operation.
-max-quota size Specifies the maximum quota size, in kilobytes (KB). The -max-quota flag is used to modify the default value of the maximum quota only when a consumer is registered.
-min-quota size Specifies the minimum quota size, in KB. The -min-quota flag is used to modify the default value of the minimum quota only when a consumer is registered.
-name consumer Specifies the name of the consumer for a specific operation.
-password-file file Specifies the path of the file that contains the password for the consumer that is specified by the -name flag.
Note: The security of the file that is specified by the -password-file flag is the responsibility of the user who runs the pksctl command.
-shrink-max new_size Decreases the maximum quota size of a registered consumer to the value specified by the new_size variable. The consumer for which the size of the maximum quota is decreased is specified by the -name parameter.
-type {multi | single} Denotes the session concurrency that is allowed for the consumer who is specified by the -name parameter. The following values are the valid values for the -type flag:
  • multi: Specifies that multiple sessions are allowed for the consumer.
  • single: Specifies that the consumer is a single-session consumer. The default value is single.
.

Security

Attention RBAC users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in Security. For a list of privileges and the authorizations that are associated with this command, see the lssecattr command or the getcmdattr subcommand.

Exit status

The pksctl command returns the following exit values:
Table 2. Exit status
Item Description
0 Successful completion of the specified operation.
>0 An error occurred. In such cases, appropriate error messages are displayed wherever applicable.

Files

Table 3. Files
Item Description
/usr/sbin/pksctl Contains the pksctl command.