How to Change the Settings of CMD-Auth

1 General Consideration

The format of the settings is JSON.
There are three ways of supplying the main settings of the application:

  1. through the instance data service of the cloud provider (i.e. AWS AMI User Data)
  2. through a custom URL
  3. through a custom file

2 Settings supplied through instance data

The settings of the application should be specified when preparing target machine. This is done with the help of the instance data (i.e. AWS AMI User Data).
IMPORTANT! It is mandatory to make the metadata available. When preparing the machine make sure the option Metadata Accessible is set to Enabled or equivalents.
CMD-Auth is able to read both AWS AMI User Data IMDSv1 and IMDSv2. IMDSv2 is the first choice.

3 Settings supplied through a custom URL or a custom file

It is possible to use a custom URL or a custom file in order to supply settings for the application.
When using a custom URL or a custom file it becomes very easy to change the settings while the machine is running. The systemd unit will still require a restart as follows:

  • cmd-auth-init.service - if adjusting setting application > systemd_slice_percentage
  • cmd-auth.service - if adjusting other settings

Restarting unit cmd-auth.service is very fast and by comparison faster than a full restart done by unit cmd-auth-init.service.
In order to start using custom settings, modify the file /etc/cmd-auth/env/systemd.env by adjusting one of the environment variables APP_SETTINGS_URL or APP_SETTINGS_PATH.
After changing one of the variables APP_SETTINGS_URL or APP_SETTINGS_PATH, the main systemd unit(s) require a restart as listed above.

Restarting systemd units is not desirable in production, so you may want to adjust APP_SETTINGS_URL or APP_SETTINGS_PATH automatically during installation: 

env APP_SETTINGS_URL="http://custom.url" dnf install ...

, or 

env APP_SETTINGS_PATH="/etc/..." dnf install ...

4 Settings Details

The settings are described in detail by the documentation of the application.

5 Automatic Adjustment of Settings

If the settings are not provided or if the format of the settings is invalid, the application uses default values for settings at individual, section or global level.
At the same time the values of most settings must meet certain criteria in order to be accepted.
The documentation of the application indicates the default values and acceptable ranges/values for each setting.
The official settings generator includes validity checks (ranges, patterns etc.).
In order to view the real values of the settings used by the application an administrator can use route GET /admin/application/settings (sensitive information is hidden), or consult file /var/lib/cmd-auth/settings/data.json.

6 Settings Generator

A complete settings generator is available online for accounts which are validated. The settings generator includes validity checks (ranges, patterns etc.) and extracts from the documentation.

7 Changing the settings after the machine was started

Use endpoint PUT /admin/application/custom-settings in order to adjust the settings of a live application. This endpoint will not change the main settings supplied by any of the means listed above.
Remember that this operation will act only on the machine which receives the command.
Consecutive calls to endpoint PUT /admin/application/custom-settings are not cumulative. Each call alters only the settings specified in relation with the resulting settings of the application, a combination of main settings and defaults (if some settings are not specified or unacceptable).
In order to apply adjusted settings, the application runs a brief restart.
After finding a good set of settings that fit your needs, always update also the main settings (instance data or the settings supplied through a custom URL or a custom file) if not already done. This procedure becomes critical if using Launch Templates and load-balancers.

Add Your Question
FAQs