4.2 Managing Configuration Files

Advanced File Configurator enables you to manage configuration files of Administration Console, Identity Server, and Access Gateway. When you need to make any customization in a file’s default values, you add and modify that file on Advanced File Configurator. Therefore, Advanced File Configurator maintains only modified configuration files.

You can perform the following actions:

  • Upload a single file or multiple files from a cluster, modify them, and add as configuration files in Administration Console to a cluster

  • Compare, modify, and merge changes into configuration files across devices

  • Download configuration files of a specific cluster

  • Send the configuration to devices

  • Search for a specific configuration file based on various parameters, such as modification type and description

  • Untrack configurations

  • Remove configuration

IMPORTANT:

  • Ensure that all devices of a cluster are up and running while performing any file operation. Else, you might get inconsistent results.

  • Customized files remain available on the device even after a device is removed from the cluster.

4.2.1 Adding Configurations to a Cluster

Access Manager provides various configuration files with default settings. When you need to make any customization in a file’s default values, you add and modify that file on Advanced File Configurator. Therefore, the Advanced File Configurator lists only modified configuration files.

For modifying a configuration file or folder, you need to add it to the UI first if not added already. You can add a folder in the ZIP or tar.gz format. The name of the folder must be the same as it is specified in Folder Path. For example, you want to upload a folder to /opt/novell/nam/idp/webapps/nidp/jsp. In this case, ensure that the name of the folder is jsp and the format is ZIP or tar.gz.

You can add files and folders using one of the following approaches based on the requirement:

  • Upload a file or a folder:You can download files from a server by using Download Configurations to Edit Offline, modify these offline, verify the changes, and then upload it to Advanced File Configurator by using Upload Configurations. This approach is useful for making considerable changes.

  • Edit configurations on the server: Fetch a file or folder from a server, modify it online, and add to Advanced File Configurator. This approach is useful for making small changes.

IMPORTANT:

  • For adding a configuration file, at least one cluster of that component must be configured and the server health must be green.

  • Permissions associated with a file or folder are inherited when you add a new file or folder. Access Manager retains permissions of the parent folder while replacing an existing file or folder.

  • When you add a folder, it overwrites the existing folder on the server completely. If you have modified only a few files in the folder and want to retain other files, add the modified files individually to Advanced File Configurator instead of using the folder upload option.

  • server.xml contains the specific keystore password and server address in connectors for each device. While applying changes from this file, IP addresses and keystore passwords available in the server.xml connectors for that device are retained.

Perform the following steps to add a file or a folder to a cluster:

  1. In Administration Console Dashboard, click Advanced File Configurator.

  2. Select the device-specific tab based on your requirement. For example, if you want to add a file for Access Gateway, select the Access Gateway tab.

  3. Click the plus icon ( ) and select one of the following options:

    • Edit Configurations on the Server: To make a minor change in a file, you can fetch the file from any device of a cluster and make the required change in File > File Editor.

    • Upload Configurations: To make considerable changes. Such as for JSP customizations, you can fetch a file from a device, download, modify it offline, verify the changes, and then upload it from your local system using this option.

    • Download Configurations to Edit Offline: To verify configurations and making offline changes, you can download files from a server.

    The following steps are for Edit Configurations on the Server and Upload Configurations options. If you want to download files from a server, see Downloading Files from a Server.

  4. Specify the following details:

    Field

    Description

    Type

    To add a single file, perform the following actions:

    1. Select File.

    2. Select the file in File Name. Access Manager lists the default files.

    3. File Path displays the default location for the selected file. Modify the location if required.

    To add a folder, perform the following actions:

    1. Select Folder.

    2. Select the location to add files in Folder Path. Access Manager lists the default folder locations. You can specify a custom location if the list does not contain the desired location.

      For the list of default locations, see Access Manager Configuration Folders.

    Cluster Name

    Select the cluster for which you want to add files. This option does not apply to Administration Console.

    Source

    Add files or folders by using one of the following approaches based on the option you have selected in Step 3:

    • If you have selected Upload Configurations, click Browse and select the required file. If you have selected Folder under Upload Type, you can upload files only in the ZIP format.

      NOTE:Ensure that the size of the file that you are uploading does not exceed 120 MB.

    • If you have selected Edit Configurations on the Server, select the device from which you want to import the file, and click Fetch File.

    File

    Click File Editor to make the required changes or compare it with the same file from any server of the same or another cluster.

    For information about comparing files, see Comparing Configuration Files.

    Restart <component name>

    Turn on the toggle if the configuration changes in this file require the service restart to take effect.

    • For Identity Server and Access Gateway: When this option is enabled, you are prompted to perform Update All for the relevant cluster after sending changes to devices. After updating the server, the device-specific service is restarted.

    • For Administration Console: When this option is enabled, after sending changes to devices, Advanced File Configurator displays a message indicating the service restart is required. Restart Administration Console manually by running the following commands:

      /etc/init.d/novell-ac restart

      Or

      systemctl restart novell-ac.service

    Temporary Modification

    Turn on the toggle if you do not want to retain this configuration change in the next Access Manager upgrade.

    This option helps you identify the files that you need to remove after the upgrade. For example, a temporary code fix. If this is turned on, you must remove this file manually after the upgrade.

    Modification Type

    Select the type of modification from the list. You can specify the type manually if the list does not contain the required type.

    You can later use this information to search for files that are updated for a specific type. For example, you can search for all files for which Modification Type is Security Setting.

    Description

    Specify the details of the changes you have made in the file. As you might require to update the configurations many times over the period, you can use these details to track when and what changes were done in the file. You can also use this information as criteria to search for specific files.

  5. Click OK.

  6. To apply the configurations of this file, continue with Applying Configurations to Devices.

4.2.2 Exporting and Importing Configurations

You can replicate configurations across clusters of the same or different Access Manager setups.

Scenario 1: Replicating configuration changes between two clusters of the same setup (cluster1 and cluster2):

  1. Export configurations from cluster1. See Exporting Configurations from a Cluster.

  2. Import configurations to cluster2. See Importing Configurations.

Scenario 2: Replicating configuration changes between two different Access Manager setups (setup1 and setup2):

  1. Export the configuration files from setup1. See Exporting Configurations from a Cluster.

  2. Go to setup2 and import the configurations that you exported from setup1. See Importing Configurations.

Exporting Configurations from a Cluster

You can export configuration files, which are available on Administration Console, of a cluster. You can use the exported configurations to perform the following tasks:

  • Import these configurations to another cluster of the same Access Manager setup

  • Import these configurations to a cluster of another Access Manager setup

  • Take a backup of the configuration files

To export configurations, perform the following steps:

  1. In Administration Console Dashboard, click Advanced File Configurator.

  2. Select the device-specific tab based on your requirement. For example, if you want to export Access Gateway configurations, select the Access Gateway tab.

  3. Select the cluster which configurations you want to export.

  4. Click More Options () > Export Configurations.

  5. Save the file. By default, the file is saved as customFiles.tar.gz. The compressed file mirrors the folder structure of the file system.

Importing Configurations

You can import configurations, which are exported using Advanced File Configurator, to achieve the following tasks:

  • To replicate configurations of a cluster to another cluster of the same setup

  • To replicate configurations of an Access Manager setup to another setup

To import configurations, perform the following steps:

  1. In Administration Console Dashboard, click Advanced File Configurator under Administration Tasks.

  2. Select the device-specific tab based on your requirement. For example, if you want to import Access Gateway configurations, select the Access Gateway tab.

  3. Click More Options () > Import Configurations.

  4. In Upload Configuration, browse to and select the exported configurations. The file must be in the tar.gz format.

  5. Map Source Cluster with Destination Cluster. The files downloaded from the source clusters will be imported to the mapped destination clusters.

    This mapping is not required for Administration Console.

  6. Click Next.

    • If a file is added to Advanced File Configurator before the import, it will be replaced with the copy available in the imported tar.gz file.

    • If a file is added to Advanced File Configurator before the import, no change happens if the imported tar.gz file does not contain it.

    • A file is added from the imported from the tar.gz file if it is not available in Advanced File Configurator.

  7. Click Finish.

4.2.3 Comparing Configuration Files

Advanced File Configurator provides a tool for comparing and modifying files and folders. Using this tool, you can perform the following actions:

  • Compare a file with the same file from a specific device. You can select a folder also for comparison. If you select a folder, all files of that folder become available in the tool for comparison. You can compare the files one after the other.

  • Modify a file.

  • Undo changes you made in a single file or multiple files.

  • Download files for offline modifications.

You can access the tool on the following pages:

  • Add Configuration

  • Edit Configuration

Understanding the Compare View

Files are highlighted in different colors based on the comparison between the current and server files. The following table lists various indicators on the File Editor page:

State

Description

No color

Both the current file and the fetched file are identical.

Green

This is a new file in Advanced File Configurator for this cluster. This file is not available on the server selected for comparison.

Red

The file exists on the server and Advanced File Configurator. However, the content of files or folders differ.

Asterisk

The current file is modified in File Editor.

Comparing and Modifying Files and Folders in File Editor

  1. On the Add Configuration or Edit Configuration page, turn on File Editor.

    Condition

    Action

    Compare a file while adding it

    Turn on the File > File Editor toggle on the Add Configuration page. See Adding Configurations to a Cluster.

    Compare a file while editing it

    Turn on the File > File Editor toggle on the Edit Configuration page. See Modifying Configurations.

  2. In File Editor, turn on Compare with a server file.

  3. In Select Device, select the device from which you want to import files to compare, and click Fetch.

  4. In Files, select the file that you want to compare. The file opens in Current File.

    If you have imported a folder for comparison, select files one after the other for comparison.

  5. The corresponding fetched file opens in Server File. For example, if you have selected web.xml in Files, Server File displays web.xml imported from the selected device.

  6. Now, you can perform the following actions:

    • Compare both files.

    • Modify the current file.

    • Undo changes made in the current file. If you have made any change in the current file and want to undo it, click the revert icon in Current File. To undo all changes, click the revert icon in Files.

    • Download files for offline modifications. You can fetch a file or folder and download it for offline modification.

      For example, you can fetch and download files if you require making considerable changes in configurations. You can modify files offline, verify the changes, and then upload it to the appropriate cluster.

      The files are downloaded in the ZIP format. The ZIP file contains the file that you select for the comparison and the file from the server. Similarly, you can download multiple files also if you have selected a folder for comparison.

  7. Click Save.

Managing server.xml Changes

The server.xml file contains keystore passwords and IP addresses specific to each server. The changes from server.xml are distinctly sent to each server. While applying changes from this file, IP addresses and keystore passwords available in the server.xml connectors for that device will be fetched and merged to the new server.xml.

Addresses are retained based on the port number mentioned in the connectors. Keystore passwords are retained based on the keystoreFile names in the connectors.

For example, the Identity Server cluster has three nodes: IDP 1, IDP 2, and IDP 3. The following are the snippets from server.xml of each Identity Server:

IDP 1:

<Connector NIDP_Name="connector_2" address="122.22.22.22"
keystoreFile="/opt/novell/devman/jcc/certs/idp/provider.keystore" keystorePass="efg"
maxThreads="600" port="8444" ... />

IDP 2:

<Connector NIDP_Name="connector_2" address="144.44.44.44"
keystoreFile="/opt/novell/devman/jcc/certs/idp/connector.keystore" keystorePass="hij"
maxThreads="600" port="8443" ... />

IDP 3:

<Connector NIDP_Name="connector_2" address="155.55.55.55"
keystoreFile="/opt/novell/devman/jcc/certs/idp/provider.keystore" keystorePass="klm"
maxThreads="600" port="8444" ... />

Now, you modify server.xml of IDP 1 and increase MaxThreads to 800 through Advanced File Configurator as follows:

<Connector NIDP_Name="connector_2" address="122.22.22.22"
keystoreFile="/opt/novell/devman/jcc/certs/idp/provider.keystore" keystorePass="efg"
maxThreads="800" port="8444" ... />

After applying this change to the cluster, server.xml of other Identity Servers are modified as follows:

IDP 2

<Connector NIDP_Name="connector" address="144.44.44.44"
keystoreFile="/opt/novell/devman/jcc/certs/idp/connector.keystore" keystorePass="hij"
maxThreads="800" port="8443" ... />

IDP 3

<Connector NIDP_Name="connector_2" address="155.55.55.55"
keystoreFile="/opt/novell/devman/jcc/certs/idp/provider.keystore" keystorePass="klm"
maxThreads="800" port="8444" ... />

The address and passwords are retained in the modified files. However, the required MaxThreads value is appropriately modified in each server.xml.

4.2.4 Modifying Configurations

Important Points to Consider before Modifying Configurations:

  • For a default file, the file shipped with the product is backed up. You can revert the configuration to the file shipped with the product if required. However, any intermediate version of the file is not backed up automatically. Access Manager does not back up any file that is not available with the production installation. Therefore, it is recommended to take a backup of any file before you modify it.

  • The server.xml file is specific to each device as it contains the specific keystore password and server address in connectors. While applying changes from this file, IP addresses and keystore passwords available in server.xml connectors for that device are retained. See Managing server.xml Changes.

  • Permissions associated with the parent file or folder are inherited when you add a new file or folder. Access Manager retains the permissions of the parent folder while replacing an existing file or folder.

  • When you upload a folder, it overwrites the existing folder on the server completely. If you have modified only a few files in the folder and want to retain other files, add the modified files individually instead of using the folder upload option.

  • File Editor does not verify the correctness of syntax and invalid characters in a file.

Perform the following steps to modify a configuration file or folder:

  1. In Administration Console Dashboard, click Advanced File Configurator.

  2. Select the device-specific tab based on your requirement. For example, if you want to modify an Access Gateway file, select the Access Gateway tab.

  3. Expand the cluster for which you want to modify a file or folder.

    If the required file is not available here, add it. For information about how to add a file, see Section 4.2.1, Adding Configurations to a Cluster.

  4. Click the file or folder that you want to modify.

  5. Make the following changes as required:

    Field

    Description

    Replace with New File

    If you want to replace the existing file or folder with another version, upload the required file or folder from your local system.

    1. Select Upload.

    2. Browse and select the required file. If you have selected Folder under Upload Type, you can upload files only in the ZIP format.

    File

    Click File Editor. In this editor, you can compare the file with a file from another server and make the changes in the file.

    If you select Replace with New File, the new file is opened in the editor.

    For information about comparing files, see Comparing Configuration Files.

    Restart <component name>

    Turn on the toggle if the configuration changes in this file require the service restart to take effect.

    • For Identity Server and Access Gateway: When this option is turned on, you are prompted to perform Update All for the relevant cluster after sending changes to devices. After updating the server, the device-specific service is restarted.

    • For Administration Console: When this option is turned on, after sending changes to devices, Advanced File Configurator displays a message indicating the service restart is required. Restart Administration Console manually by running the following commands:

      /etc/init.d/novell-ac restart

      Or

      systemctl restart novell-ac.service

      NOTE:Ensure to restart the IDP server after modifying the configurations.

    Temporary Modification

    Turn on the toggle if you do not want to retain this configuration change in the next Access Manager upgrade.

    This option helps you identify the files that you need to remove after the upgrade. For example, a temporary code fix. If this is turned on, you must remove this file manually after the upgrade.

    Modification Type

    Select the type of modification from the list. You can specify the type manually if the list does not contain the required type.

    You can later use this information to search for files that are updated for a specific type. For example, you can search for all files for which Modification Type is Security Setting.

    Description

    Specify the details of the changes you have made in the file. As you might require to update the configurations many times over the period, you can use these details to track when and what changes were done in the file. You can also use this information as criteria to search for specific files.

  6. Click OK.

  7. To apply the configuration changes, continue with Applying Configurations to Devices.

4.2.5 Applying Configurations to Devices

After you add or modify configurations, perform the following steps to apply changes to a cluster:

  1. In Administration Console Dashboard, click Advanced File Configurator.

  2. Select the device-specific tab based on your requirement. For example, if you want to apply changes from an Access Gateway file, select the Access Gateway tab.

  3. Expand the cluster to which you want to apply configurations.

  4. Select the configuration file.

  5. Click the Send Configurations to Servers icon ().

    • If the server restart after modification is not required for the selected file, the changes are applied to devices.

    • If the server restart after modification is required for the selected file, a message is displayed indicating the requirement to click Update All on the respective server page.

      Perform one of the following actions based on the component for which you are applying configurations:

      • Identity Server: Click Update All on the Identity Servers page.

      • Access Gateway: Click Update All on the Access Gateways page.

      • Administration Console: Restart Tomcat by running the /etc/init.d/novell-ac restart or systemctl restart novell-ac.service command.

IMPORTANT:The server.xml file is specific to each device as it contains the specific keystore password and server address in connectors. While applying changes from this file, IP addresses and keystore passwords available in server.xml connectors for that device are retained.

4.2.6 Downloading Files from a Server

You can download configuration files directly from any of the devices of a cluster. You can use this capability for the following purposes:

  • Verifying configurations

  • Making offline changes

Perform the following steps to download files from a server:

  1. In Administration Console Dashboard, click Advanced File Configurator.

  2. Select the device-specific tab based on your requirement. For example, if you want to download Access Gateway files, select the Access Gateway tab.

  3. Click the plus icon () and select Download Configurations to Edit Offline.

  4. Specify the following details:

    Field

    Description

    Select Device

    Select the IP address of the device from which you want to download files.

    Path

    Specify the path from which you want to download files.

    For example, /opt/novell/nesp/lib/webapp/WEB-INF/classes/.

  5. Click Download and save the file.

4.2.7 Untracking Configurations

You can remove configuration files from Advanced File Configurator. This action does not remove the configurations from devices. However, configurations from an untracked file are not applied to a new node. Untracking a file does not delete the file from the server.

To untrack a file, perform the following steps:

  1. In Administration Console Dashboard, click Advanced File Configurator.

  2. Select the device-specific tab based on your requirement. For example, if you want to untrack an Access Gateway configuration, select the Access Gateway tab.

  3. Select the corresponding configuration files.

  4. Click More Options () > Untrack Configurations.

  5. Click OK.

4.2.8 Removing Configurations

When you remove a configuration file from the Configuration Files page, changes made to the cluster configuration using this file are removed.

The following are the possible outcomes:

  • Configuration files, which come with the product installation, are reverted to their original version. Examples of such files are tomcat.conf, server.xml, and so forth.

  • Other configuration files are removed from all servers. For example, removing configurations from a custom authentication file will delete this file from all servers.

Perform the following steps to remove configurations:

  1. In Administration Console Dashboard, click Advanced File Configurator.

  2. Select the device-specific tab based on your requirement. For example, if you want to delete an Access Gateway file, select the Access Gateway tab.

  3. Select the file that you want to delete. You can delete multiple files simultaneously.

  4. Click the Remove Configurations icon ().

  5. Click OK.

    The server restart is required for completing the delete process for some files. When prompted, update the server.

4.2.9 Post-Upgrade Considerations

Post-upgrade, the file status might display Configuration sent successfully. However, all customized configurations might not be available on the virtual machine. To ensure that all customizations are available, perform the following steps:

  1. Edit each file or folder added in the Advanced File Configuration table. For more information, see Modifying Configurations.

  2. Compare each file or folder with the file or folder available on the server by using File Editor. If required, update customizations in File Editor and save the changes. For more information, see Comparing and Modifying Files and Folders in File Editor.

  3. Click the Send Configurations to Servers icon for all the files and folders added in the Advanced File Configuration table. For more information, see Applying Configurations to Devices.

  4. Verify if customized configurations are sent to the device by comparing the files using File Editor.