Setting environment variables for Config Sync

Locating information for the environment variables

The following list explains how to obtain the setting for each of the environment variables.

*_MGMT_SERVER

This property specifies the hostname and path that provides access to the REST API endpoint for your catalog. Locate toolkit.endpoint property in the toolkit credentials.json file that you downloaded in Downloading and extracting the API Connect Config Sync utility, and set the *_MGMT_SERVER variable to the value of the toolkit.endpoint property.

The value might look like the following example:

https://platform-api.hostname.com/api

*_TOOLKIT_CREDENTIALS_CLIENTID, *_TOOLKIT_CREDENTIALS_CLIENTSECRET

The toolkit credentials clientID and clientSecret are used to authenticate the utility to be able to make REST API calls against the API Connect cluster. Locate following properties in the toolkit credentials.json file that you downloaded in Downloading and extracting the API Connect Config Sync utility, and set the environment variables as shown:

• Set the *_TOOLKIT_CREDENTIALS_CLIENTID variable to the value of the toolkit.client_id property
• Set the *_TOOLKIT_CREDENTIALS_CLIENTSECRET variable to the value of the toolkit.client_secret property

*_ORG

This is the short name of the provider organization in which your catalog is hosted. Set the *_ORG variable to the value of the provider organization's Name property.

To locate the provider organization name, complete the following steps:

1. Log in to the API Manager.
2. From the Home tab, select Manage settings.
3. On the Settings page, click the Overview tab and locate the value of the Name property (not the Title).

*_REALM

This property specifies the identity provider realm of the API Manager registry for your instance of API Connect. Set the *_REALM variable to the value of the realm name. This parameter is not required in API Connect instances with single-sign-on (SSO) enabled on the API Manager user registry (for example, API Connect Enterprise as a Service on AWS). Instead, you authenticate using an API key (see *_API_KEY for details).

To obtain the realm name, run the following toolkit CLI command:

apic identity-providers:list --scope provider --server <mgmt_endpoint_url> --fields title,realm

where <mgmt_endpoint_url> is the API Manager URL with any segments (for example, /manage) removed from the end of the URL. If you have access to the Cloud Manager user interface, you can view the configured endpoint URLs as described in Viewing platform and UI endpoints.

The following example shows a response listing the available realms for a deployment:

apic identity-providers:list --scope provider --server <mgmt_endpoint_url> --fields title,realm

total_results: 2
results:
  - title: 'API Manager User Registry'
    realm: 'provider/default-idp-2'
  - title: 'Common Services User Registry'
    realm: 'provider/common-services'

In the example, the realm for the API Manager registry is provider/default-idp-2.

For more information on obtaining the realm name, see How to determine the identity provider.

*_CATALOG

This property indicates the name of the Catalog that you want to synchronize. Set the *_CATALOG variable to the value of the catalog's Name property.

To locate the catalog name, complete the following steps:

1. Log in to the API Manager UI.
2. From the Home tab, select Manage catalogs.
3. Select the tile for the catalog you want to synchronize.
4. Click the Catalog settings tab.
5. On the Settings page, locate the value of the catalog's Name property (not the Title).

*_ADMIN_USER

This property is the name of the user account under which you will authenticate to the catalog. Set the *_ADMIN_USER variable to the value of the username that the utility will log in with to perform the synchronization task. This parameter is not required in API Connect instances with single-sign-on (SSO) enabled on the API Manager user registry (for example, API Connect Enterprise as a Service on AWS). Instead, you authenticate using an API key (see *_API_KEY for details).

In the source catalog, the user must be a Catalog Administrator or Organization Administrator with the ability to create consumer objects on behalf of the end users. In the target catalog, the user must have authorization to update catalog settings and enable or disable the hash_client_secret property.

To confirm the username, complete the following steps:

1. Log in to the API Manager UI with the user account you will use to synchronize the catalog.
2. Click the username in the page header.
3. Select My account.
4. Locate the value of the Username property.

*_ADMIN_PASSWORD

In most cases you will authenticate to the API Manager with the password associated to your username. Set the *_ADMIN_PASSWORD property to your password, being careful with any non-alphanumeric characters that may be in your password. This parameter is not required in API Connect instances with single-sign-on (SSO) enabled on the API Manager user registry (for example, API Connect Enterprise as a Service on AWS). Instead, you authenticate using an API key (see *_API_KEY for details).

Attention: If you set the *_ADMIN_PASSWORD variable, then skip the *_ADMIN_APIKEY variable. Do not set both variables when synchronizing a particular catalog.

*_ADMIN_APIKEY

In API Connect instances with single-sign-on (SSO) enabled on the API Manager user registry (for example API Connect Enterprise as a Service), you must authenticate using an API key instead of your password.

To locate your API key, complete the following steps:

1. Log in to the API Manager UI using your IBM ID.
2. In the page header, click and select My API Keys.
3. On the My API Keys page, click Add.
4. Set a title and description for your new API key and click Create.
5. Copy the new API key from the dialog box.

Attention: If you set the *_ADMIN_APIKEY variable, then skip the *_ADMIN_PASSWORD variable. Do not set both variables when synchronizing a particular catalog.

Setting the environment variables

• Mac and Linux x86:

  On Mac or Linux x86, you can either export the environment variables individually on the command line directly or create a script to export the environment variables and source that file from the command line, as in the following example:

  # Properties for source catalog
  export SOURCE_MGMT_SERVER=https://yoursourcehostname.com/path
  export SOURCE_ORG=sourceporg
  export SOURCE_REALM=provider/default-idp-2
  export SOURCE_ADMIN_USER=sourceadmin
  export SOURCE_ADMIN_PASSWORD=sourceadminpassword
  #export SOURCE_ADMIN_APIKEY=1010101010101010
  export SOURCE_CATALOG=sourcecatalog
  export SOURCE_TOOLKIT_CREDENTIALS_CLIENTID=00000000-0000-0000-0000-000000000000
  export SOURCE_TOOLKIT_CREDENTIALS_CLIENTSECRET=11111111-1111-1111-1111-111111111111
  
  # Properties for target catalog
  export TARGET_MGMT_SERVER=https://yourtargethostname.com/path
  export TARGET_ORG=targetporg
  export TARGET_REALM=provider/default-idp-2
  export TARGET_ADMIN_USER=targetadmin
  export TARGET_ADMIN_PASSWORD=targetadminpassword
  #export TARGET_ADMIN_APIKEY=2020202020202020
  export TARGET_CATALOG=targetcatalog
  export TARGET_TOOLKIT_CREDENTIALS_CLIENTID=22222222-2222-2222-2222-222222222222
  export TARGET_TOOLKIT_CREDENTIALS_CLIENTSECRET=33333333-3333-3333-3333-333333333333

  In the example, notice that the command to set the *_ADMIN_APIKEY variable is commented out because the *_ADMIN_PASSWORD is used instead.

• Windows:
  On Windows, you can set each environment variable individually by opening a command window and running the following command for each variable:

  setx <variable_name> "<variable_value>"

  where:

  • <variable_name> is the name of the environment variable to set
  • <variable_value> is the value to set for the specified variable name

  Alternatively, you can create a batch file that uses the setx command to set the environment variables, as in the following example:

  REM Properties for source catalog
  setx SOURCE_MGMT_SERVER "https://yoursourcehostname.com/path"
  setx SOURCE_ORG "sourceporg"
  setx SOURCE_REALM "provider/default-idp-2"
  setx SOURCE_ADMIN_USER "sourceadmin"
  setx SOURCE_ADMIN_PASSWORD "sourceadminpassword"
  REM setx SOURCE_ADMIN_APIKEY "1010101010101010"
  setx SOURCE_CATALOG "sourcecatalog"
  setx SOURCE_TOOLKIT_CREDENTIALS_CLIENTID "00000000-0000-0000-0000-000000000000"
  setx SOURCE_TOOLKIT_CREDENTIALS_CLIENTSECRET "11111111-1111-1111-1111-111111111111"
  
  REM Properties for target catalog
  setx TARGET_MGMT_SERVER "https://yourtargethostname.com/path"
  setx TARGET_ORG "targetporg"
  setx TARGET_REALM "provider/default-idp-2"
  setx TARGET_ADMIN_USER "targetadmin"
  setx TARGET_ADMIN_PASSWORD "targetadminpassword"
  REM setx TARGET_ADMIN_APIKEY "2020202020202020"
  setx TARGET_CATALOG "targetcatalog"
  setx TARGET_TOOLKIT_CREDENTIALS_CLIENTID "22222222-2222-2222-2222-222222222222"
  setx TARGET_TOOLKIT_CREDENTIALS_CLIENTSECRET "33333333-3333-3333-3333-333333333333"

  In the example batch file, notice that the command to set the *_ADMIN_APIKEY variable is commented out because the *_ADMIN_PASSWORD is used instead.

Optional environment variables