User Account Types

The sysadmin Account

This is a local, per-host, sudo-enabled account created automatically when a new host is provisioned.

This Linux user account is used by the primary system administrator as it has extended privileges.

On controller nodes, this account is available even before ansible bootstrap playbook is executed, during the initial system install.

On the initial system install, the default initial password is sysadmin.

• The initial password must be changed immediately when you log in to the system for the first time during the initial system install. For details, see Installation guide.

• The sysadmin account, and its current password, is created automatically on new hosts added to the system.

• After each unsuccessful login attempt, a 3 second delay is imposed before allowing another attempt. After five consecutive unsuccessful login attempts, further attempts are blocked for about five minutes. On further attempts within 5 minutes, the system will display a message such as:

  Account locked due to 6 failed logins

  Note

  You are alerted on the 6th and subsequent attempts:

  Account locked due to 6 failed logins

  and an error message is displayed on subsequent attempts:

  Maximum number of tries exceeded (5)

  To clarify, 5 mins after the account is locked, the failed attempts will be reset and failed attempts re-counted.

• All authentication attempts are recorded in the file /var/log/auth.log of the target host.

Subsequent password changes must be executed on the active controller in an unlocked, enabled, and available state to ensure that they propagate to all other unlocked-active hosts in the cluster. Otherwise, they remain local to the host where they were executed, and are overwritten on the next reboot or host unlock to match the password on the active controller.

From the sysadmin account, you can execute commands requiring different privileges.

• You can execute non-root level commands as a regular Linux user directly.

  If you do not have sufficient privileges to execute a command as a regular Linux user, you may receive a permissions error, or in some cases, the command may be reported as not found.

• You can execute root-level commands as the root user.

  To become the root user, use the sudo command to elevate your privileges, followed by the command to be executed. For example, to run the license-install command as the root user:

  $ sudo /usr/sbin/license-install license_file
  

  If a password is requested, provide the password for the sysadmin account.

• You can execute StarlingX administrative commands as the Keystone admin user and Kubernetes kubectl and helm administrative commands as the kubernetes-admin user.

  To become the admin / kuberentes-admin user from the Linux sysadmin account, source the script /etc/platform/openrc:

  $ source /etc/platform/openrc
  [sysadmin@controller-0 ~(keystone_admin)]$
  

  The system prompt changes to indicate the newly acquired privileges.

  Note

  The default Keystone prompt includes the host name and the current working path. For simplicity, this guide uses the following generic prompt instead:

  ~(keystone_admin)]$
  

Keystone Accounts

StarlingX uses Keystone for authentication and authorization of users of the StarlingX REST APIs, the CLI, the Horizon Web interface and the Local Docker Registry. StarlingX’s Keystone uses the default local SQL Backend.

System-Critical Keystone User Accounts

The following Keystone user accounts are system-critical and cannot be deleted:

• admin

• mtce

• fm

• barbican

• sysinv

• patching

• dcorch

• vim

• dcagent

• dcmanager

• dcdbsync

• smapi

• usm

Note

These Keystone user accounts are essential for the operation and management of the platform. Deleting or modifying these accounts could lead to unexpected behavior or system instability.

Keystone Accounts Overview

StarlingX uses the default admin project for managing all StarlingX resources,

e.g. system, hosts, networks.

StarlingX uses configured user accounts to manage access to StarlingX resources, and images in the Local Docker Registry.

You can create and manage Keystone users from the web management interface, the CLI, or the StarlingX’s Keystone REST API.

When a user is added in the central cloud of a Distributed Cloud system, it is propagated to the managed subclouds. To check if this new user is already present in a host, use the openstack user list command.

In StarlingX, the default authentication backend for Keystone users is the local SQL Database Identity Service.

Note

All Keystone accounts are subject to system password rules. For complete details on password rules, see System Account Password Rules.

Keystone Account Authentication

StarlingX users are authenticated by the Keystone identity service.

For user authentication, StarlingX’s Keystone identity service supports the local SQL Database authentication backend.

Keystone Account Roles

In StarlingX, 4 different keystone roles are supported: admin, configurator, operator, and reader.

• Users with an admin role in the admin project can execute any action in the system.

• The configurator role is the same as admin role, however it cannot add/remove users/groups (Keystone commands), cannot add/remove system secrets (Barbican commands) nor add/remove trusted CAs (system ca-certificate-install/uninstall commands).

• The operator role has read-only access to everything, however can execute operational commands on hosts (example: lock/unlock, resets, power off/on) and can execute operational commands on subclouds (example: manage/unmanage, backup management).

• Users with a reader role in the admin project have read-only access. They cannot perform any changes in the system but can read any configuration. In the CLI, commands with prefix or suffix, such as, list, query, show and summary get the configuration from the system, and are allowed for this type of user, all other commands are denied.

The following sections describe how to create users with specific keystone roles in StarlingX.

Manage Keystone Accounts

You can create and manage Keystone users from the web management interface, the CLI, or the StarlingX’s Keystone REST API.

Creation of user with specific role

Use the following commands to add a new user named daveuser with password “Passw0rd*” and role reader:

~(keystone_admin)]$ openstack user create daveuser --project admin --password Passw0rd*

~(keystone_admin)]$ openstack role add --project admin --user readeruser reader

See:

https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html for details on managing Keystone users and roles.

Keystone Password Recovery for details on how to change or reset a Keystone user password.

System Account Password Rules for details on password rules, as all keystone accounts are subject to system password rules.

Change the Admin Password on Distributed Cloud for details on changing the keystone admin user password across the entire Distributed Cloud system.

Configure the Keystone Token Expiration Time

You can change the default Keystone token expiration setting. This may be required to provide sustained access for operations that take more than an hour.

About this task

By default, the Keystone token expiration time is set to 3600 seconds (1 hour). This is the amount of time a token remains valid. The new setting must be between 3600 seconds and 14400 seconds.

Procedure

1. On the active controller, become the Keystone admin user.

   $ source /etc/platform/openrc
   

2. Ensure that the token_expiration parameter is defined for the identity service.

   $ system service-parameter-list | grep token_expiration
   
   | 712e4a45-777c-4e83-9d56-5042cde482f7 | identity | config | token_expiration | 3600
   

3. Modify the service parameter using the following command:

   $ system service-parameter-modify identity config token_expiration=7200
   

4. Apply the configuration change.

   $ system service-parameter-apply identity
   
   Applying identity service parameters
   

   Allow a few minutes for the change to take an effect.

Keystone Password Recovery

About this task

This section describes how to change or reset a Keystone user password.

Procedure

• Do one of the following to change a Keystone admin user password at any time.

  • Use the Identity panel in the Horizon Web interface.

  • Use the following command from the controller CLI.

    ~(keystone_admin)]$ openstack user password set
    

• Use the following command to reset a Keystone non-admin user (tenant user) account.

  ~(keystone_admin)]$ openstack user set --password <temp_password> <user>
  

  where <user> is the username and <temp_password> is a temporary password.

  Note

  During system bootstrap, the platform does not support the use of quotation characters in the keystone user password.

Keystone Security Compliance Configuration

About this task

You can configure custom password rules for keystone security compliance.

Procedure

1. Use the following parameters to set the rules for keystone security compliance.

   system service-parameter-add identity security_compliance unique_last_password_count
   system service-parameter-add identity security_compliance password_regex
   system service-parameter-add identity security_compliance password_regex_description
   system service-parameter-add identity security_compliance password_expires_days
   

   Note

   password_expire_days must be a positive integer.

   [sysadmin@controller-0 ~(keystone_admin)]$ system service-parameter-add identity security_compliance password_expires_days=90
   +-------------+--------------------------------------+
   | Property    | Value                                |
   +-------------+--------------------------------------+
   | uuid        | 27d24c80-e9de-37ce-9d26-f21236782be8 |
   | service     | identity                             |
   | section     | security_compliance                  |
   | name        | password_expires_days                |
   | value       | 90                                   |
   | personality | None                                 |
   | resource    | None                                 |
   +-------------+--------------------------------------+
   

2. In order for the changes to take effect, apply the new configuration with the command:

   system service-parameter-apply identity
   

   For security reasons these parameters are validated:

   • unique_last_password_count must be an integer equal or greater than zero.

   • password_regex must be a valid regex conforming to the Python Regular Expression (RE) syntax: https://docs.python.org/3/library/re.html.

   • password_regex_description must be a non empty string.

   Note

   The password_regex_description will be used by keystone as part of the error message when the user tries a password that does not conform to the rules. Make sure to have an explanatory description.

   For example:

   [sysadmin@controller-0 ~(keystone_admin)]$ system service-parameter-add identity security_compliance unique_last_password_count=7
   +-------------+--------------------------------------+
   | Property    | Value                                |
   +-------------+--------------------------------------+
   | uuid        | 27e18c80-e8be-47ce-9b24-f21136682de6 |
   | service     | identity                             |
   | section     | security_compliance                  |
   | name        | unique_last_password_count           |
   | value       | 7                                    |
   | personality | None                                 |
   | resource    | None                                 |
   +-------------+--------------------------------------+
   [sysadmin@controller-0 ~(keystone_admin)]$ system service-parameter-add identity security_compliance password_regex='^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[!@#$%^&*()<>{}+=_\\\[\]\-?|~`,.;:]).{20,}$'
   +-------------+---------------------------------------------------------------------------------+
   | Property    | Value                                                                           |
   +-------------+---------------------------------------------------------------------------------+
   | uuid        | bab59259-4463-4bce-a6ed-e7b2dcfeb2ac                                            |
   | service     | identity                                                                        |
   | section     | security_compliance                                                             |
   | name        | password_regex                                                                  |
   | value       | ^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[!@#$%^&*()<>{}+=_\\\[\]\-?|~`,.;:]).{20,}$ |
   | personality | None                                                                            |
   | resource    | None                                                                            |
   +-------------+---------------------------------------------------------------------------------+
   [sysadmin@controller-0 ~(keystone_admin)]$ system service-parameter-modify identity security_compliance password_regex_description='Password must have a minimum length of 20 characters, and must contain at least 1 upper case, 1 lower case, 1 digit, and 1 special character'
   +-------------+----------------------------------------------------------------------------------------------------------------------------------------------+
   | Property    | Value                                                                                                                                        |
   +-------------+----------------------------------------------------------------------------------------------------------------------------------------------+
   | uuid        | 83ae409e-d5b5-4465-b71b-f29b81bdcb67                                                                                                         |
   | service     | identity                                                                                                                                     |
   | section     | security_compliance                                                                                                                          |
   | name        | password_regex_description                                                                                                                   |
   | value       | Password must have a minimum length of 20 characters, and must contain at least 1 upper case, 1 lower case, 1 digit, and 1 special character |
   | personality | None                                                                                                                                         |
   | resource    | None                                                                                                                                         |
   +-------------+----------------------------------------------------------------------------------------------------------------------------------------------+
   [sysadmin@controller-0 ~(keystone_admin)]$
   [sysadmin@controller-0 ~(keystone_admin)]$ system service-parameter-apply identity
   Applying platform service parameters
   

3. The system service-parameter-apply command will apply the configuration to /etc/keystone/keystone.conf and restart the keystone service.

4. After that, the new rules are already in place, and they can be used.

   [sysadmin@controller-1 ~(keystone_admin)]$ openstack user password set
   Current Password:
   New Password:
   Repeat New Password:
   The password does not match the requirements: 20 characters minimum, must have numbers and special characters. (HTTP 400) (Request-ID: req-3aa0f2f9-eef8-4f28-8e3c-ae4a7eaf1d29)
   

LDAP Accounts

Local LDAP Accounts

Local LDAP Linux User Accounts

LDAP users are required for SSH access to local StarlingX Ansible playbooks and scripts , as well as for interacting with Kubernetes services via the Kubernetes CLI tools. The local LDAP setup offers a dedicated StarlingX solution for managing these user accounts and access controls.

You can create local LDAP accounts using the StarlingX LDAP service.

Note

For security reasons, it is recommended that ONLY the highest level admin users be granted SSH access to the StarlingX nodes. Standard admin users and non-admin users should exclusively utilize remote CLI tools or web-based GUIs for system interaction.

Local LDAP accounts are centrally managed on the active controller; all hosts in the cloud/cluster use the Local LDAP server on the active controller for SSH and console authentication. And all subclouds in a Distributed Cloud system, use the Local LDAP server on the active controller of the Central Cloud for SSH and console authentication.

Local LDAP user accounts share the following set of attributes:

• The initial password is the name of the account.

• The initial password must be changed immediately upon first login.

• For complete details on password rules, see System Account Password Rules.

• SSH and local console sessions are logged out automatically after about 15 minutes of inactivity.

• After each unsuccessful login attempt, a 3 second delay is imposed before allowing another attempt. After five consecutive unsuccessful login attempts, further attempts are blocked for about five minutes. On further attempts within 5 minutes, the system will display a message such as:

  Account locked due to 6 failed logins

  Note

  This delay is 3 seconds.

  You are alerted on the 6th and subsequent attempts:

  Account locked due to 6 failed logins

  and an error message is displayed on subsequent attempts.

  When you login to the console you are alerted on the 6th, and subsequent attempts:

  The account is locked due to 5 failed logins (2 minutes left to unlock)

  When you login remotely using SSH, you are allowed up to 3 attempts to enter a valid password within a single session. If all 3 attempts fail, the system will display the error message: Permission denied (publickey,password). You can continue to retry the login by starting a new login session. After a total of 5 consecutive failed attempts a user will be locked out and the error will be: Permission denied (publickey,password).

  This lockout event is recorded in the /var/log/auth.log file with the following entry: Consecutive login failures for user <user name> account temporarily locked.

  When the password lockout duration of 5 mins has passed, the failed attempts will be reset and failed attempts re-counted.

• All authentication attempts are recorded in the file /var/log/auth.log of the target host.

• Home directories and passwords are backed up and restored by the system backup utilities. Home directories are not automatically synced and are local to that host.

Default Local LDAP User Accounts

The following Local LDAP user accounts are available by default on newly deployed hosts, regardless of the host personality:

operator

A cloud administrative account, comparable to the default admin account used in the web management interface.

This user account has access to all native Linux commands not requiring root or sudo privileges, and it’s shell is preconfigured to have administrative access to StarlingX commands.

admin

A host administrative account. It has access to all native Linux commands and is included in the sudoers list.

For increased security, the admin and operator accounts are only usable from the console ports of the hosts; no SSH access is allowed.

• These accounts serve as system access redundancies in the event that SSH access is unavailable. In the event of any issues with connectivity, user lockout, or sysadmin passwords being forgotten or not getting propagated properly, the presence of these accounts can be essential in gaining access to the deployment and rectifying things. This is why these accounts are restricted to the console port only, as a form of “manual over-ride.”

See also

Create Local LDAP Linux Accounts

Create Local LDAP Linux Accounts

StarlingX includes a helper script for creating LDAP Linux accounts.

About this task

Note

For security reasons, it is recommended that ONLY the highest admin level users be allowed to SSH to the nodes of the StarlingX. Normal admin level users and Non-admin level users should strictly use remote CLIs or remote web GUIs.

Note

Local LDAP users can ONLY be added to a standalone cloud or the central cloud (systemController) in a Distributed Cloud system. Subclouds use the Local LDAP server running on the central cloud (systemController).

The Local LDAP solution on a StarlingX cloud is designed for high availability. It runs in an active/standby mode across two controllers, keeping user and group settings in sync between the active and standby local LDAP servers.

The home directory for a new LDAP Linux user will be created after the first login, as: /home/<username>. At the same time, the user will be prompted to change the default password to a secure password based on mandatory format rules.

The ldapusersetup command provides an interactive method for setting up LDAP Linux user accounts.

Prerequisites

For convenience, identify the user’s Keystone account user name in StarlingX.

Procedure

1. Log in as sysadmin, and start the ldapusersetup script.

   controller-0: ~$ sudo ldapusersetup
   

2. Follow the interactive steps in the script.

   1. Provide a user name.

      Enter username to add to LDAP: teamadmin
      

      Successfully added user teamadmin to LDAP
      Successfully set password for user teamadmin
      Warning : password is reset, user will be asked to change password at login
      

   2. Specify whether the user should have sudo capabilities or not. Enabling sudo privileges allows the LDAP users to execute the following operations:

      • sw_patch to unauthenticated endpoint

      • docker and/or crictl commands to communicate with the respective daemons

      • Utilities show-certs.sh and license-install (recovery only)

      • IP configuration for local network setup

      • Password change of local openldap users

      • Access to restricted files, example: restricted logs

      • Manual reboots

      Add teamadmin to sudoer list? (yes/NO): yes
      Successfully added sudo access for user teamadmin to LDAP
      

      Note

      There is another procedure to add sudo capabilities to a local LDAP linux account. For details, see Add LDAP Users to Linux Groups Using PAM Configuration. It is recommended to use either of the procedures but not both to avoid overlapping.

   3. Specify a secondary user group for this LDAP user. For example, sys_protected group.

      The purpose of having OpenLDAP/WAD users as a part of the sys_protected group on the StarlingX platform is to allow them to execute the StarlingX system operations via source/etc/platform/openrc. The LDAP user in the sys_protected group will be equivalent to the special sysadmin bootstrap user, and will have the following:

      • Keystone admin/admin identity and credentials

      • Kubernetes /etc/kubernetes/admin.conf credentials

      Add teamadmin to secondary user group? (yes/NO): yes
      Secondary group to add user to? [sys_protected]:
      Successfully added user teamadmin to group cn=sys_protected,ou=Group,dc=cgcs,dc=local
      

      Note

      There is another procedure to add sys_protected capabilities to a local LDAP linux account. For details, see Add LDAP Users to Linux Groups Using PAM Configuration. It is recommended to use either of the procedures but not both to avoid overlapping.

   4. Change the password duration.

      Enter days after which user password must be changed [90]:
      

      Successfully modified user entry uid=ldapuser1, ou=People, dc=cgcs, dc=local in LDAP
      Updating password expiry to 90 days
      

   5. Change the warning period before the password expires.

      Enter days before password is to expire that user is warned [2]:
      

      Successfully modified user entry uid=teamadmin,ou=People,dc=cgcs,dc=local in LDAP
      Updating password expiry to 2 days
      

On completion of the script, the command prompt is displayed.

controller-0: ~$

Results

The Local LDAP account is created.

Alternatively, a set of LDAP commands is available to operate on LDAP user accounts. The commands are installed in the directory /usr/local/sbin, and are available to any user account in the sudoers list. Included commands are lsldap, ldapadduser, ldapdeleteuser, and several others starting with the prefix ldap.

Use the command option –help on any command to display a brief help message, as illustrated below.

$ ldapadduser --help
Usage : /usr/local/sbin/ldapadduser <username> <groupname | gid> [uid]
$ ldapdeleteuser --help
Usage : /usr/local/sbin/ldapdeleteuser <username | uid>

Also alternatively, for managing composite Local LDAP Accounts (i.e. with associated Keystone and Kubernetes accounts) for a standalone cloud or a distributed cloud, see Manage Composite Local LDAP Accounts at Scale.

Create LDAP Linux Groups

StarlingX offers LDAP commands to create and manage LDAP Linux groups as part of the ldapscripts library.

About this task

The main commands that manage LDAP Linux groups are: ldapaddgroup , ldapaddusertogroup, ldapdeletegroup, ldapdeleteuserfromgroup.

To list all the commands in the ldapscripts library, the following command can be used:

sysadmin@controller-0:~$ ls /usr/sbin/ldap*
/usr/sbin/ldapaddgroup             /usr/sbin/ldapid
/usr/sbin/ldapaddmachine           /usr/sbin/ldapinit
/usr/sbin/ldapaddsudo              /usr/sbin/ldapmodifygroup
/usr/sbin/ldapadduser              /usr/sbin/ldapmodifymachine
/usr/sbin/ldapaddusertogroup       /usr/sbin/ldapmodifysudo
/usr/sbin/ldapdeletegroup          /usr/sbin/ldapmodifyuser
/usr/sbin/ldapdeletemachine        /usr/sbin/ldaprenamegroup
/usr/sbin/ldapdeletesudo           /usr/sbin/ldaprenamemachine
/usr/sbin/ldapdeleteuser           /usr/sbin/ldaprenameuser
/usr/sbin/ldapdeleteuserfromgroup  /usr/sbin/ldapsetpasswd
/usr/sbin/ldapfinger               /usr/sbin/ldapsetprimarygroup
/usr/sbin/ldapgid                  /usr/sbin/ldapusersetup

The LDAP commands usage information can be found from man pages or using the “–help” option. For example, this is the usage information for creating or adding a LDAP Linux group.

sysadmin@controller-0:~$ ldapaddgroup --help
Usage : /usr/sbin/ldapaddgroup <groupname> [gid]

sysadmin@controller-0:~$ man ldapaddgroup
ldapaddgroup(1)             General Commands Manual
ldapaddgroup(1)
NAME
       ldapaddgroup - adds a POSIX group entry to LDAP.

SYNOPSIS
       ldapaddgroup <groupname> [gid]

OPTIONS
       <groupname>
              The name of the group to add.
       [gid]  The gid of the group to add. Automatically computed if
       not specified.

LDAP Linux group command examples:

Create a group

$ sudo ldapaddgroup group-test
Successfully added group group-test to LDAP

Add a user to the group

$ sudo ldapaddusertogroup user-test group-test
Successfully added user user-test to group cn=group-test,ou=Group,
dc=cgcs,dc=local

Delete a user membership from the group

sysadmin@controller-0:~$ ldapdeleteuserfromgroup --help
Usage : /usr/sbin/ldapdeleteuserfromgroup <username | dn> <groupname | gid>
$ sudo ldapdeleteuserfromgroup user-test group-test
Successfully deleted user user-test from group cn=group-test,ou=Group,
dc=cgcs,dc=local

Delete a group

sysadmin@controller-0:~$ ldapdeletegroup --help
Usage : /usr/sbin/ldapdeletegroup <groupname | gid>
$ sudo ldapdeletegroup group-test
Successfully deleted group cn=group-test,ou=Group,dc=cgcs,dc=local
from LDAP

After the execution of a LDAP Linux group command, the command prompt is displayed.

controller-0: ~$

Delete Local LDAP Linux Accounts

About this task

When a LDAP user account is created in the LDAP server, using sudo ldapusersetup command, a corresponding LDAP Linux user is created on the StarlingX by mapping the LDAP user attributes to Linux user attributes. The delete operation of a LDAP Linux account involves both the deletion from the Linux system as well as the deletion of the corresponding LDAP server object.

Procedure

The following steps describe the procedure to delete LDAP Linux accounts.

1. Optional step: Logged in as sysadmin, check that the user exists on StarlingX using one of the commands:

   id <username>
   

   getent passwd <username>
   

2. Delete LDAP user.

   ~(keystone_admin)]$ sudo ldapdeleteuser <username>
   

   This command will remove the LDAP user from both the LDAP server as well as from the Linux platform.

3. Check that the LDAP user was removed from the local LDAP server.

   ~(keystone_admin)]$ sudo ldapsearch -x -LLL -b dc=cgcs,dc=local
   

   or

   ~(keystone_admin)]$ sudo ldapfinger <username>
   

   Note

   SSSD service will sync-up LDAP linux users from the LDAP server, and this might take several minutes because is done according to ldap_enumeration_refresh_timeout time interval setting.

4. Check that the local LDAP Linux user was removed from the cloud platform.

   ~(keystone_admin)]$ id <username>
   

   or

   ~(keystone_admin)]$ getent passwd <username>
   

The LDAP Linux user home directory still exists after the user has been removed.

The Linux home directories of the deleted Linux LDAP users will be managed (e.g. cleaned up) by the system administrator. The platform will not remove them together with the removal of the user.

The system administrator can backup (off system) and/or delete the home directories.

Password Recovery for Local LDAP User Accounts

You can reset the password for an LDAP account as follows:

$ sudo ldapmodifyuser <user> replace userPassword <temp_password>
$ sudo ldapmodifyuser <user> replace shadowLastChange 0

where <user> is the username, and <temp_password> is a temporary password. The second command forces a password change on first login.

Local LDAP user password expiry control

About this task

Password expiry control for local openLDAP users is based on a SSSD solution. The solution uses SSSD configuration for a shadow password expiry policy based on openLDAP password policy control schema, see https://www.ietf.org/archive/id/draft-behera-ldap-password-policy-10.html.

Setting shadow password expiry information in local LDAP server

When creating a local LDAP user with ldapusersetup command or using the LDAP playbook (i.e. manage_local_ldap_account.yml), the following input data needs to be provided:

For example:

Enter days after which user password must be changed [90]: 30 Successfully modified user entry uid=usertest1,ou=People,dc=test,dc=local in LDAP Updating password expiry to 30 days.

In the example above this input sets shadowMax attribute for the LDAP user “usertest1”.

For example:

Enter days before the password is to expire that user is warned [2]: 14 Successfully modified user entry uid=usertest1,ou=People,dc=test,dc=local in LDAP Updating password expiry to 14 days.

In the example above this input sets shadowWarning attribute for the LDAP user “usertest1”.

Important

Always set the shadowMax` value higher than the shadowWarning value.

The LDAP user entry can be checked with the following command:

[sysadmin@controller-0 ~(keystone_admin)]$ /var/home/sysadmin# sudo ldapfinger usertest1

dn: uid=usertest1,ou=People,dc=test,dc=local
objectClass: account
objectClass: posixAccount
objectClass: shadowAccount
objectClass: top
cn: usertest1
uid: usertest1
uidNumber: 10002
gidNumber: 100
homeDirectory: /home/usertest1
gecos: usertest1
description: User account
loginShell: /bin/bash
shadowMax: 30
shadowWarning: 14
userPassword: <encrypted password>
shadowLastChange: 19574

Note

SSSD has been configured to use the shadow password policy by setting parameter ldap_pwd_policy=shadow. As a result, the SSSD parameters, ldap_user_shadow_max and ldap_user_shadow_warning map to the LDAP user attributes “shadowMax” and “shadowWarning” respectively.

Password Expiry behavior on a running system

Every node where SSSD client is running, in either standalone or Distributed Cloud system configurations, the following behavior will be observed.

• At login time, including SSH connections, the user will be prompted to change the password when password has expired according to the expiry period set at user account creation (shadowMax).

• A password expiration warning will appear at login time to notify the user in advance, according to the configured warning time set at the user account creation (shadowWarning).

• A warning that the password has expired is logged in “/var/log/auth.log”.

Depending on how much time is left until the password expiration, the user will be notified with the time left until expiry.

• If there is more than one day until expiry, the user will be notified with the number of days left.

• If there is less than a day till password expiry, the notification will be in number of hours.

• If it is less than one hour until expiry the notification will be in number of minutes.

For example,

• “Your password will expire in 2 day(s).” or

• “Your password will expire in 45 minute(s).”

Note

The password expiry warning is displayed as a duplicate message at login.

For example:

usertest2@<host IP address>’s password: Your password will expire in 1 day(s). Your password will expire in 1 day(s).

This is normal behavior because the messages are posted by 2 different sources that check password expiry.

The source of the 2 notifications for password expiry can be found in the “/var/log/auth.log”. One notification comes from “sshd” and the 2nd from“sudo”.

Example:

2023-08-09T02:25:29.375 controller-0 sshd[1788048]: info pam_sss(sshd:account): User info message: Your password will expire in 21 hour(s).

2023-08-09T02:25:29.377 controller-0 sshd[1788048]: info Accepted password for usertest3 from <ip addr> port <port_number> ssh2

…

2023-08-09T02:27:03.284 controller-0 sudo: info pam_sss(sudo:account): User info message: Your password will expire in 21 hour(s).

Note

Password expiration warning gets triggered when the regular LDAP user is using ssh to connect to the node the user needs access to and its password has reached the threshold for a warning before it expires. The first warning message may occur with a delay. This is due to time calculation and synchronization mechanism with the LDAP server.

Remote Windows Active Directory accounts

User accounts in the remote Windows Active Directory are managed directly by its corresponding server. For detailed instructions on managing users and groups, refer to the appropriate external documentation for the remote Windows Active Directory.

Manage Composite Local LDAP & Keystone Accounts at Scale

About this task

The purpose of this playbook is to simplify and automate the management of composite Local LDAP accounts across multiple DC systems or standalone systems. A composite Local LDAP account is defined as a Local LDAP account that also has a unique Keystone account with same name (in the Admin Project) and a specified Keystone role. The Local LDAP account can be optionally set with sudo and/or sys_protected privileges. If the created LDAP account is assigned sys_protected privileges, it will have access to a K8S serviceAccount with cluster-admin role credentials.

A user with such a composite Local LDAP account can SSH to systems’ controllers and subclouds and:

• execute Linux commands (with local LDAP account credentials; with or without sudo capabilities),

• execute StarlingX CLI commands (with its Keystone account credentials) and

• execute K8S CLI commands if the LDAP account has sys_protected privileges (with credentials of a cluster-admin K8S serviceAccount).

A unique Local LDAP account and unique Keystone account enables user-specific command audit logging for security and tracking purposes.

The playbook can be used to create or delete such composite Local LDAP Accounts, manage access to sudo capabilities and manage password change parameters.

Create Inventory File Using Ansible-Vault

Users are required to create an inventory file to specify playbook parameters. Using ansible-vault is highly recommended for improved security. An ansible-vault password needs to be created during this step, which is required for subsequent access to the ansible-vault and ansible-playbook commands.

Create a secure inventory file:

~(keystone_admin)]$ ansible-vault create secure-inventory

This will open a text editor where you can fill the inventory parameters as shown in the example below. When this ansible playbook runs locally, this inventory will always have the same contents except for the value of <sysadmin-password>.

[all:vars]
ansible_user=sysadmin
ansible_password=<sysadmin-password>
ansible_become_pass=<sysadmin-password>

[systemcontroller]
systemcontroller-0 ansible_host=127.0.0.1

The inventory parameters are:

ansible_user

Specify the sysadmin user for ansible to use.

ansible_password

The sysadmin password.

ansible_become_pass

The sysadmin password for using sudo.

systemcontroller-0 ansible_host

The target DC/Standalone system controller IP Address or FQDN to create/delete the composite Local LDAP account. Use 127.0.0.1, loopback address, if running the ansible playbook locally on the target DC/Standalone system controller.

Run the Playbook

After the inventory file is created, the ansible playbook can be run to perform the user creation or removal process. The previously created ansible-vault password will be prompted during runtime.

~(keystone_admin)]$ ansible-playbook --inventory secure-inventory --ask-vault-pass --extra-vars='user_id=na-admin mode=create' /usr/share/ansible/stx-ansible/playbooks/manage_local_ldap_account.yml

Extra-vars parameter options:

• user_id

  <string>

  Username that will be used for both the Local LDAP account and the Keystone account (in the Admin Project) on the target DC/Standalone system and associated DC Subclouds.

• mode (optional, default is “create”):

  create

  Creates users within Local LDAP and Keystone.

  delete

  Removes existing users from Local LDAP and Keystone.

• sudo_permission (optional, default is “no”):

  yes

  The created Local LDAP user will have sudo capabilities to execute commands with root privileges on the DC/Standalone system and associated DC Subclouds.

  no

  The created Local LDAP user will NOT have sudo capabilities to execute commands with root privileges on the DC/Standalone system and associated DC Subclouds.

• sys_protected (optional, default is “no”):

  yes

  The created Local LDAP user will be added to sys_protected group, and will be able to access a K8S serviceAccount with cluster-admin role credentials.

  no

  The created Local LDAP user will NOT be added to sys_protected group.

• user_role (optional, default is “admin”):

  admin

  Set the Keystone role of the user to be created as admin. This role has permissions to execute all StarlingX CLI commands.

  configurator

  Set the Keystone role of the user to be created as configurator. For this user role permission, see Introduction to User Management.

  operator

  Set the Keystone role of the user to be created as operator. For this user role permission, see Introduction to User Management.

  reader

  Set the Keystone role of the user to be created as reader. This role has permissions to only execute passive display-type (e.g. list, get) StarlingX CLI commands.

• password_change_period (optional, default is “90”):

  <int>

  Specifies the maximum number of days that the Local LDAP account’s password is valid.

• password_warning_period (optional, default is “2”):

  <int>

  Specifies the number of days before password expiration that the Local LDAP user is warned.

Note

There is another procedure to set sudo and sys_protected capabilities for a local LDAP account. For details, see Add LDAP Users to Linux Groups Using PAM Configuration. It is recommended to use either of the procedures but not both to avoid overlapping.

Use the Created Composite Local LDAP Accounts

For subclouds that were “managed” and with identity_sync_status “in-sync” when the playbook run (this can be checked with command dcmanager subcloud show <subcloud-name>), it may take up to 2 minutes for the created Keystone account to propagate to these subclouds.

For subclouds that are not “managed” or were added after the playbook run, it is sufficient to set these subclouds as “managed” and wait for them to have identity_sync_status “in-sync”.

If the created Local LDAP user has sudo permission, it may take up to 5 minutes for this permission to reach all nodes.

To test the created composite Local LDAP account, SSH to a cloud and execute:

$ source local_starlingxrc
Enter the password to be used with Keystone user na-admin:
Created file /home/na-admin/na-admin-openrc
~(keystone_na-admin)]$ system host-list
+----+--------------+-------------+----------------+-------------+--------------+
| id | hostname     | personality | administrative | operational | availability |
+----+--------------+-------------+----------------+-------------+--------------+
| 1  | controller-0 | controller  | unlocked       | enabled     | available    |
+----+--------------+-------------+----------------+-------------+--------------+

The operator should always execute source local_starlingxrc to load Keystone credentials. This command prompts the user for the Keystone password, stores it in the local file <USER>-openrc and loads it. Subsequent calls of source local_starlingxrc will just load the created local openrc file.

Troubleshooting

This section describes common problems and their solutions.

~(keystone_na-admin)]$ system host-list
Must provide Keystone credentials or user-defined endpoint and token, error was: The request you have made requires authentication. (HTTP 401)

The error above happens either because the Keystone password is wrong and/or because the Keystone user has not been propagated to all subclouds. Check if the password is correct in the contents of the local file <USER>-openrc. Check the system controller if all subclouds are “managed” and with identity_sync_status “in-sync”. Wait for 2 minutes after the playbook is run for Keystone user propagation in the subclouds that are already in a “managed” state, and with identity_sync_status “in-sync”.

~(keystone_na-admin)]$ sudo ls -la
Password:
na-admin is not allowed to run sudo on controller-0. This incident will be reported.

The error above happens either because the LDAP account was created without sudo permission or because the sudo permission for this LDAP account did not reach the current node. Check if the playbook was run with sudo_permission=yes. Wait 5 minutes for sudo permission to sync.

Password Rules

System Account Password Rules

StarlingX enforces a set of strength requirements for new or changed passwords.

The following rules apply to all System Accounts (Local LDAP, sysadmin, other Linux Accounts, and Keystone accounts):

• The password must be at least 12 characters long.

• You cannot reuse the last 5 passwords in history.

• The password must contain:

  • at least one lower-case character

  • at least one upper-case character

  • at least one numeric character

  • at least one special character

Note

During system bootstrap, the platform does not support the use of quotation characters in the keystone user password.

The following additional rules apply to Local Linux accounts only (Local LDAP, sysadmin, and other Linux accounts):

• A changed password must differ from the previous password by at least three characters.

  Note

  This rule does not apply when the root user changes the password for other users, including sudo to root, to change other account’s password.

• A changed password using only character case differences is not allowed. For example, if nEtw!rk5 is the current password, Netw!RK5 is not allowed as the new password.

  Note

  This rule does not apply when the root user changes the password for other users, including sudo to root, to change other account’s password.

• After five consecutive incorrect password attempts, the user is locked out for 15 minutes.

For more details on Linux Accounts password rules see: Linux Accounts Password Rules.

Warning

Ageless passwords are not supported in StarlingX.

Linux Accounts Password Rules

Check Current Password Expiry Settings

Before making any changes, you may want to check the current password expiry settings for the user. You can do this by running the chage -l <username> command, replacing <username> with the name of the user whose password expiry settings you want to view.

sudo chage -l <username>

Change Password Expiry Settings

To change the password expiry period of Linux accounts, run the chage command, as below:

[sysadmin@controller-0 ~(keystone_admin)]$ sudo chage -M <days_to_expiry> -I <days_to_inactive> <username>

• -M <days_to_expiry>: Sets the maximum number of days a password is valid (90 days by default).

• -I <days_to_inactive>: Sets the number of days of inactivity after a password expires before the account is disabled (45 days by default).

For example, to set a maximum password age of 60 days and configure the account to be permanently disabled 45 days after the password expires for the user sysadmin, run the following command:

[sysadmin@controller-0 ~(keystone_admin)]$ sudo chage -M 60 -I 45 sysadmin

Verify Changes

After making the changes, verify that the new password expiry settings have been applied by running the chage -l <username> command again.

chage -l <username>

For the example above of user sysadmin and expiry period of 60 days, the output of chage -l <username> should be as follows:

[sysadmin@controller-0 ~(keystone_admin)]$ chage -l sysadmin
Last password change                                : Apr 09, 2025
Password expires                                    : Jun 08, 2025
Password inactive                                   : Jul 23, 2025
Account expires                                     : never
Minimum number of days between password change      : 1
Maximum number of days between password change      : 60
Number of days of warning before password expires   : 7