IBM Developer

Tutorial

Rootvg LV encryption support for preservation and migration installations

Add Platform KeyStore (PKS) encryption using VIOS media repository

By

Durgarao Simhadri

On this page

Introduction

IBM AIX 7.3 TL3 introduced support for encrypting and decrypting rootvg logical volumes (LVs) during preservation and migration installations. While the NIM repository also supports this feature, this tutorial focuses on preservation and migration installation using the VIOS media repository.

The enhancement in AIX 7.3 TL3 adds LV encryption support for default rootvg LVs during preservation and migration installations. Users can choose to encrypt rootvg LVs using the Platform KeyStore (PKS) authentication method or decrypt them based on the input provided during the installation process.

PKS is a hardware backed non-volatile random access memory (NVRAM) that offers secured storage for sensitive material. With the PKS encryption authentication method, rootvg LVs will be automatically unlocked without user intervention.

Prerequisites to enable PKS encryption

Users need to make sure that the following prerequisites are fulfilled to enable PKS encryption for rootvg logical volumes during preservation and migration installation of an AIX logical partition (LPAR), using VIOS media repository:

  • Ensure that PKS is enabled for the AIX LPAR on the Hardware Management Console (HMC) that manages the corresponding central processor complex (CPC).

    In the HMC GUI, on the partition properties page for the AIX logical partition, in the Advanced Settings section, for Platform KeyStore Size parameter, ensure that a minimum value of 4 KB is set. This setting enables PKS for the AIX LPAR. Before setting this parameter value, power-off the LPAR and power-on the LPAR, once the value is set.

    alt

    If PKS is already enabled for the AIX LPAR, ensure sufficient free PKS slots are available. Use hdcryptmgr pksshow AIX command to confirm this.

  • To host the media repository, identify a VIOS partition on the same CPC as that of the AIX logical partition. Ensure that a virtual Small Computer System Interface (VSCSI) connection between the identified VIOS partition and the AIX LPAR exists. On my test VIOS, vhost1 represents the VSCSI connection between my test VIOS and my test AIX LPAR: 

   (0) root @ aix-lpar: /
   # kdb
              START              END <name>
   0000000000001000 0000000008450000 start+000FD8
   F00000002FF47600 F00000002FFE1000 __ublock+000000
   000000002FF22FF4 000000002FF22FF8 environ+000000
   000000002FF22FF8 000000002FF22FFC errno+000000
   F1001004C0000000 F1001004D0000000 pvproc+000000
   F1001004D0000000 F1001004D8000000 pvthread+000000
   read vscsi_scsi_ptrs OK, ptr = 0xF10009D5B0129F00
   (0)> cvai
   NAME       STATE    CMDS_ACTIVE  ACTIVE_QUEUE       HOST
   vscsi0     0x000007 0x0000000000 0x0                vios-lpar->vhost1
   vscsi1     0x000007 0x0000000000 0x0                mainvios->vhost62
   (0)> exit
   (0) root @ aix-lpar: /
   #

   (0) padmin @ vios-lpar: /home/padmin
   $ lsmap -vadapter vhost1 -dec
   SVSA            Physloc                                      Client Partition ID
   --------------- -------------------------------------------- ------------------
   vhost1          U9080.HEX.134C1B8-V59-C4                     66
   VTD                   NO VIRTUAL TARGET DEVICE FOUND
   (0) padmin @ vios-lpar: /home/padmin
   $

Steps to perform preservation and migration installation

Perform the following steps to perform preservation and migration installation of an AIX LPAR with PKS encryption enabled on rooting logical volumes using the VIOS media repository:

  1. On the VIOS partition, get the installation distribution media ISO file and loop mount the ISO file.

    (0) root @ vios-lpar: /home/padmin
# ls -lt ./ISO/AIX_v7.3_7300-03-00_DVD_1_of_2.iso
-rw-r-----    1 root     staff    4237524992 Dec 12 01:19 ./ISO/AIX_v7.3_7300-03-00_DVD_1_of_2.iso

(0) root @ vios-lpar: /home/padmin
# mkdir /home/padmin/mnt

(0) root @ vios-lpar: /home/padmin
# loopmount -i ./ISO/AIX_v7.3_7300-03-00_DVD_1_of_2.iso -o "-V cdrfs -o ro" -m /home/padmin/mnt/

(0) root @ vios-lpar: /home/padmin
#

  2. Extract the ISO file contents to customize the bosinst.template file to make rootvg LV PKS encryption user selections.

    (0) root @ vios-lpar: /home/padmin
# mkdir AIX_v7.3_7300-03-00_DVD_1_of_2.iso_extracted

(0) root @ vios-lpar: /home/padmin
# cp -hR /home/padmin/mnt/* /home/padmin/AIX_v7.3_7300-03-00_DVD_1_of_2.iso_extracted/

(0) root @ vios-lpar: /home/padmin
#

  3. Customize the bosinst.template file located under ./usr/lpp/bosinst/, within the extracted folder.

    Here are the parameters in the bosinst.template, possible parameter values, and the description.

    The following are the valid values for the INSTALL_METHOD parameter:

    • Overwrite: Performs a clean installation
    • Preserve: Preserves all the non-system logical volumes
    • Migrate: Migrates the AIX OS version across major releases, preserving all system logical volumes

    The following are the valid values for the PROMPT parameter:

    • Yes: Performs prompt mode of installation
    • No: Performs non-prompt mode of installation

    The following are the valid values for LV encryption in preservation and migration installation:

    • Preserve: The Preserve mode retains the previous LV encryption state for all the LVs. This mode is the default mode for LV encryption.
    • No: The No mode disables LV encryption for all the LVs and keeps the LVs plain. When the LV encryption option is No, all the encrypted LVs are decrypted during the installation operation.
    • Yes: The Yes mode enables LV encryption in the selected LVs. The values provided in the lv_encryption stanza are considered.

    The following values are valid for each rootvg LV name in the lv_encryption stanza:

    • Preserve: PKS retains the previous PKS encryption state of the LV
    • No: PKS decrypts the LV
    • Yes: PKS encrypts the LV

    Note that multiple target_disk_data stanzas need to be mentioned – one stanza for each rootvg member hdisk on the AIX LPAR.

    Here is a customized bosinst.template sample file for a non-prompt mode of migration installation case:

    (0) root @ vios-lpar: /home/padmin
# cat /home/padmin/AIX_v7.3_7300-03-00_DVD_1_of_2.iso_extracted/usr/lpp/bosinst/bosinst.template
control_flow:
    CONSOLE = Default
    INSTALL_METHOD = migrate
    INSTALL_EDITION = standard
    PROMPT = no
    EXISTING_SYSTEM_OVERWRITE = yes
    INSTALL_X_IF_ADAPTER = yes
    RUN_STARTUP = yes
    RM_INST_ROOTS = no
    ERROR_EXIT =
    CUSTOMIZATION_FILE =
     INSTALL_TYPE =
    BUNDLES =
    RECOVER_DEVICES = Default
    BOSINST_DEBUG = yes
    ACCEPT_LICENSES = yes    
    ACCEPT_SWMA = yes
    DESKTOP = NONE
    INSTALL_DEVICES_AND_UPDATES = yes
    IMPORT_USER_VGS =
    ALL_DEVICES_KERNELS = yes
    GRAPHICS_BUNDLE = yes
    SYSTEM_MGMT_CLIENT_BUNDLE = yes
    OPENSSH_CLIENT_BUNDLE = no
    OPENSSH_SERVER_BUNDLE = no
    FIREFOX_BUNDLE = no
    KERBEROS_5_BUNDLE = no
    SERVER_BUNDLE = no
    REMOVE_JAVA_5 = yes
    HARDWARE_DUMP = yes
    ADD_CDE = no
    ADD_GNOME = no
    ADD_KDE = no
    ERASE_ITERATIONS = 0
    ERASE_PATTERNS =
    MKSYSB_MIGRATION_DEVICE =
    TRUSTED_AIX = no
    TRUSTED_AIX_LSPP =
    TRUSTED_AIX_SYSMGT =
    SECURE_BY_DEFAULT = no
    ENCRYPTLV = yes
    ADAPTER_SEARCH_LIST =

lv_encryption:
    ROOT_HD4 = yes
    USR_HD2 = yes
    VAR_HD9VAR = yes
    TMP_HD3 = yes
    HOME_HD1 = yes
    OPT_HD10OPT = yes
    ADMIN_HD11ADMIN = yes
    DUMPLV = yes
    PAGING_HD6LV = yes
    LIVEDUMPLV = yes

target_disk_data:
    LOCATION =
    SIZE_MB =
    HDISKNAME = hdisk0

target_disk_data:
    LOCATION =
    SIZE_MB =
    HDISKNAME = hdisk1

target_disk_data:
    LOCATION =
    SIZE_MB =
    HDISKNAME = hdisk2

target_disk_data:
    LOCATION =
    SIZE_MB =
    HDISKNAME = hdisk3

locale:
    BOSINST_LANG = en_US
    CULTURAL_CONVENTION = en_US
    MESSAGES = en_US
    KEYBOARD = en_US

(0) root @ vios-lpar: /home/padmin
#

  4. Create the customized ISO file from the extracted folder.

    (0) root @ vios-lpar: /home/padmin
# mkrr_fs 1 /home/padmin/custom_AIX_v7.3_7300-03-00_DVD_1_of_2.iso /home/padmin/AIX_v7.3_7300-03-00_DVD_1_of_2.iso_extracted/
Running mkisofs ...

mkrr_fs was successful.

(0) root @ vios-lpar: /home/padmin
# ls -lt custom_AIX_v7.3_7300-03-00_DVD_1_of_2.iso
-rw-r--r--    1 root     staff    8057147392 Dec 12 04:15 custom_AIX_v7.3_7300-03-00_DVD_1_of_2.iso

(0) root @ vios-lpar: /home/padmin
#

  5. Make the customized ISO DVD available to the AIX LPAR being migrated as a boot device. This will be accomplished using the VIOS media repository.
    a. On the VIOS partition, create a media repository in the rootvg:

       (0) padmin @ vios-lpar: /home/padmin
   $ mkrep -sp rootvg -size 6G
   Virtual Media Repository Created
   Repository created within "VMLibrary" logical volume

   (0) padmin @ vios-lpar: /home/padmin
   $ chrep -size 4G

   (0) padmin @ vios-lpar: /home/padmin
   $ lsrep
   Size(mb) Free(mb) Parent Pool         Parent Size      Parent Free
      10198    10198 rootvg                   20384              416

   Name                                                  File Size Optical         Access

   (0) padmin @ vios-lpar: /home/padmin
   $

    b. Create a virtual media disk from the custom ISO DVD:

    (0) padmin @ vios-lpar: /home/padmin
$ mkvopt -name custom_AIX_v7.3_7300-03-00_DVD_1_of_2.iso -file /home/padmin/custom_AIX_v7.3_7300-03-00_DVD_1_of_2.iso -ro

(0) padmin @ vios-lpar: /home/padmin
$

    c. Ensure that the virtual media disk created in previous step is listed in the lsrep command output and thus verify that the virtual media disk is part of the repository.

    (0) padmin @ vios-lpar: /home/padmin
$ lsrep
Size(mb) Free(mb) Parent Pool         Parent Size      Parent Free
   10198     2513 rootvg                   20384              416

Name                                                  File Size Optical         Access
AIX_v7.3_7300-03-00_DVD_1_of_2.iso                         7684 None            ro

(0) padmin @ vios-lpar: /home/padmin
$

    d. Create the file-backed optical device and map it to the AIX LPAR vhost: Note that the AIX LPAR vhost shown below does not have a vtopt device. 

    (0) padmin @ vios-lpar: /home/padmin
$ lsmap -vadapter vhost1 -dec
SVSA            Physloc                                      Client Partition ID
--------------- -------------------------------------------- ------------------
vhost1          U9080.HEX.134C1B8-V59-C4                     66
VTD                   NO VIRTUAL TARGET DEVICE FOUND
(0) padmin @ vios-lpar: /home/padmin
$

    e. Create the vtopt device:

    (0) padmin @ vios-lpar: /home/padmin
$ mkvdev -fbo -vadapter vhost1
vtopt2 Available

(0) padmin @ vios-lpar: /home/padmin
$

    Notice that the AIX LPAR vhost shown below includes a vtopt device now. 

    (0) padmin @ vios-lpar: /home/padmin
$ lsmap -vadapter vhost1 -dec
SVSA            Physloc                                      Client Partition ID
--------------- -------------------------------------------- ------------------
vhost1          U9080.HEX.134C1B8-V59-C4                     66
VTD                   vtopt2
Status                Available
LUN                   0x8100000000000000
Backing device
Physloc
Mirrored              N/A
(0) padmin @ vios-lpar: /home/padmin
$

    At this stage, the vtopt device appears as a virtual CD ROM device on the AIX LPAR (Note: The CD ROM device appears, after issuing the cfgmgr command on the AIX LPAR):

    (0) root @ aix-lpar: /
# cfgmgr

(0) root @ aix-lpar: /
# lsdev | grep cd
cd0        Available       Virtual SCSI Optical Served by VIO Server

(0) root @ aix-lpar: /
#

    f. Back on VIOS, load the virtual media disk on the vtopt device:

    (0) padmin @ vios-lpar: /home/padmin
$ lsrep
Size(mb) Free(mb) Parent Pool         Parent Size      Parent Free
   10198     2513 rootvg                   20384              416

Name                                                  File Size Optical         Access
custom_AIX_v7.3_7300-03-00_DVD_1_of_2.iso                         7684 None            ro

(0) padmin @ vios-lpar: /home/padmin
$ loadopt -vtd vtopt2 -disk custom_AIX_v7.3_7300-03-00_DVD_1_of_2.iso

(0) padmin @ vios-lpar: /home/padmin
$ lsrep
Size(mb) Free(mb) Parent Pool         Parent Size      Parent Free
10198     2513 rootvg                   20384              416

Name                                                  File Size Optical         Access
custom_AIX_v7.3_7300-03-00_DVD_1_of_2.iso                         7684 vtopt2          ro

(0) padmin @ vios-lpar: /home/padmin
$

    Verify that the vtopt2 backing device is set to the virtual media disk location.

    (0) padmin @ vios-lpar: /home/padmin
$ lsmap -vadapter vhost1 -dec
SVSA            Physloc                                      Client Partition ID
--------------- -------------------------------------------- ------------------
vhost1          U9080.HEX.134C1B8-V59-C4                     66
VTD                   vtopt2
Status                Available
LUN                   0x8100000000000000
Backing device        /var/vio/VMLibrary/custom_AIX_v7.3_7300-03-00_DVD_1_of_2.iso
Physloc
Mirrored              N/A
(0) padmin @ vios-lpar: /home/padmin
$

    Preinstallation notes on my AIX LPAR:

    • My AIX LPAR is at 72Z level. For migration installation, initial AIX level can be either at 71 or 72 levels. 
    (0) root @ aix-lpar: /
# what /unix | grep build
         _kdb_buildinfo unix_64 Nov 29 2023 09:38:25 2348A_72Z
(0) root @ aix-lpar: /
#

    Rootvg on my AIX LPAR spans across four hdisks: hdisk0, hdisk1, hdisk2, and hdisk3. Rootvg member disks could be different on AIX LPARs. Ensure target_disk_data stanzas in bosinst.template file are customized accordingly.

    (0) root @ aix-lpar: /
# lspv
hdisk0          00c4c1b895b581dd                    rootvg          active
hdisk1          00c4c1b8bac818fb                    rootvg          active
hdisk2          00c4c1b8bac8197d                    rootvg          active
hdisk3          00c4c1b8bac819fa                    rootvg          active
hdisk4          none                                None
(0) root @ aix-lpar: /
#

    None of the PKS slots on my AIX LPAR are used yet (PKS encryption is not enabled for any of the rootvg LVs on my AIX LPAR):

    (0) root @ aix-lpar: /
# hdcryptmgr pksshow 
PKS uses 32 bytes on a maximum of 4096 bytes.
PKS_Label (LVid)                         Status
PKS_Label (objects)
(0) root @ aix-lpar: /
#

  6. Initiate migration installation on the AIX LPAR. On the AIX partition, run the cfgmgr command (if not done already), and change the bootlist to boot from cd0.

    (0) root @ aix-lpar: /
# bootlist -m normal -o
hdisk0 blv=hd5 pathid=0
(0) root @ aix-lpar: /
# lsdev | grep cd
cd0        Available       Virtual SCSI Optical Served by VIO Server
(0) root @ aix-lpar: /
# bootlist -m normal cd0
(0) root @ aix-lpar: /
# bootlist -m normal -o
cd0
(0) root @ aix-lpar: /
#

  7. Reboot the AIX LPAR so that it boots from cd0 and the migration installation proceeds:

    (0) root @ aix-lpar: /
# shutdown -Fr
SHUTDOWN PROGRAM
Thu Dec 12 06:27:35 CST 2024
Running /etc/rc.d/rc2.d/Khtxd stop
Stopping htx daemon: ...
Running /etc/rc.d/rc2.d/Ksshd stop
0513-044 The sshd Subsystem was requested to stop.
Running /etc/rc.d/rc2.d/Kwpars stop
Running /etc/rc.d/rc3.d/Ksoed stop
Wait for 'Rebooting...' before stopping.
.
.
.

Post-migration installation verification

When migration installation is complete and the system prompts for user login, enter the root user credentials. On my AIX LPAR, post successful migration installation, I performed the following verifications:

  • Verified that the AIX level on the migrated LPAR is now at AIX 7.3 TL3.
     (0) root @ aix-lpar: /
 # what /unix | grep build
          _kdb_buildinfo unix_64 Nov 18 2024 09:53:27 2447A_73F
 (0) root @ aix-lpar: /
 #
  • Verified that the rootvg on the migrated AIX LPAR continue to span across the following four hdisks: hdisk0, hdisk1, hdisk2, hdisk3.
     (0) root @ aix-lpar: /
 # lspv
 hdisk0          00c4c1b895b581dd                    rootvg          active
 hdisk1          00c4c1b8bac818fb                    rootvg          active
 hdisk2          00c4c1b8bac8197d                    rootvg          active
 hdisk3          00c4c1b8bac819fa                    rootvg          active
 hdisk4          none                                None
 (0) root @ aix-lpar: /
 #
  • Verified that PKS encryption is enabled for the migrated AIX LPAR rootvg LVs, in accordance with the user’s choice.
     (0) root @ aix-lpar: /
 # hdcryptmgr pksshow
 Total PKS size: 4096 bytes
 Used  PKS size: 875 bytes
 Estimated encryption key slots: 34
 PKS_Label (LVid)                             status           Device
 00c4c1b800004c0000000193baba1eef.2           VALID KEY        hd6
 00c4c1b800004c0000000193baba1eef.4           VALID KEY        hd4
 00c4c1b800004c0000000193baba1eef.5           VALID KEY        hd2
 00c4c1b800004c0000000193baba1eef.6           VALID KEY        hd9var
 00c4c1b800004c0000000193baba1eef.7           VALID KEY        hd3
 00c4c1b800004c0000000193baba1eef.8           VALID KEY        hd1
 00c4c1b800004c0000000193baba1eef.9           VALID KEY        hd10opt
 00c4c1b800004c0000000193baba1eef.10          VALID KEY        hd11admin
 00c4c1b800004c0000000193baba1eef.11          VALID KEY        hd7
 00c4c1b800004c0000000193baba1eef.12          VALID KEY        livedump
 PKS_Label (PVuuid)                           status           Device
 PKS_Label (objects)
 (0) root @ aix-lpar: /
 # hdcryptmgr showlv rootvg
 NAME                 CRYPTO_STATUS    %ENCRYPTED       NOTE
 hd5                  not_enabled      0
 hd6                  unlocked         100
 hd8                  not_enabled      0
 hd4                  unlocked         100
 hd2                  unlocked         100
 hd9var               unlocked         100
 hd3                  unlocked         100
 hd1                  unlocked         100
 hd10opt              unlocked         100
 hd11admin            unlocked         100
 hd7                  unlocked         100
 livedump             unlocked         100
 (0) root @ aix-lpar: /
 #

Conclusion

Starting from AIX 7.3 TL3, user can use PKS to encrypt or decrypt rootvg LVs of an AIX LPAR, during a prompt mode or non-prompt mode of preservation and migration installation. This tutorial explained in detail how to enable PKS encryption to rootvg LVs, during migration installation in the non-prompt mode using a VIOS media repository.

Reference

How to configure a VIOS Media Repository/Virtual Media Library https://www.ibm.com/support/pages/how-configure-vios-media-repositoryvirtual-media-library-ex-aix-installrestore


28 January 2025

Legend