How to Configure Edge

Edge for Private Cloud v. 4.16.05

To configure Edge after installation, you use a combination of .properties files and Edge utilities. For example, to configure TLS/SSL on the Edge UI, you edit .properties files to set the necessary properties. Changes to .properties files require you to restart the affected Edge component.

Apigee refers to the technique of editing .properties files as code with config. Essentially, code with config is a key/value lookup tool based on settings in the .properties files. In code with config, the keys are referred to as tokens. Therefore, to configure Edge, you set tokens in .properties files.

Code with config allows Edge components to set default values that are shipped with the product, lets the installation team override those settings based on the installation topology, and then lets customers override any properties they choose.

If you think of it as a hierarchy, then the settings are arranges as follows with customer settings having the highest priority to override any settings from the installer team or Apigee:

1. Customer
2. Installer
3. Apigee

How to use .properties files

As a customer, you can only modify the .properties files in the /<inst_root>/apigee/customer/application directory. Each component has its own .properties file in that directory. For example, router.properties and management-server.properties.

1. Create the file in an editor as any user.
2. Chown the owner of the file to apigee:apigee or, if you changed the user running the Edge service from the apigee user, chown the file to the user who is running the Edge service.

To set a property for a component, edit the corresponding .properties file to set a token, and then restart the component:

> /<inst_root>/apigee/apigee-service/bin/apigee-service component restart

For example, after editing router.properties, restart the Router:

> /<inst_root>/apigee/apigee-service/bin/apigee-service edge-router restart

When you upgrade Edge, the .properties files in the /<inst_root>/apigee/customer/application directory are read. That means the upgrade will retain any properties that you set on the component.

Location of .properties files

There are three top-level directories for .properties files for Edge components: installation owner, and customers. The default locations are shown in the following table:

Warning: Edge customers can only modify the .properties files under /<inst_root>/apigee/customer. While you can view files under the component and installation directories, do not modify any files.

Determining the current value of a token

Before you set a token in the .properties file for the component, you can first determine its current value by using the following command:

> /<inst_dir>/apigee/apigee-service/bin/apigee-service comp configure -search token

where comp is the name of the component, and token is the token to inspect.

This command searches the hierarchy of .properties files to determine the current value of the token.

For example, to check the current value of the conf_router_HTTP.request.line.limit token for the Router:

> /<inst_dir>/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_router_HTTP.request.line.limit

You should see output in the form:

Found key conf_router_HTTP.request.line.limit, with value, 4k, in /opt/apigee/edge-router/token/default.properties

Setting tokens in .properties files

To override the value of a token:

1. Edit the .properties file for the component to set the token value. If the file does not exist, then create it.
2. Restart the component.
3. Check the token value.

For example, to set the request line limit for the Edge Router:

1. Edit the /<inst_root>/apigee/customer/application/router.properties file to set the conf_router_HTTP.request.line.limit token:
   
   conf_router_HTTP.request.line.limit=8k
2. Restart the Edge Router:
   
   > /<inst_root>/apigee/apigee-service/bin/apigee-service edge-router restart
3. Check the value of the token:
   
   > /<inst_dir>/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_router_HTTP.request.line.limit

Setting a token that takes multiple values

Some tokens take a comma separated list of values. For example, the conf_security_rbac.restricted.resources token takes a list of URIs restricted so that only the sysadmin can call them. To see the value of conf_security_rbac.restricted.resources:

> cd /<inst_root>/apigee/edge-management-server
> grep -ri "conf_security_rbac.restricted.resources" *

The output contains the following:

token/default.properties:conf_security_rbac.restricted.resources=/environments,/environments/*,/environments/*/virtualhosts,/environments/*/virtualhosts/*,/pods,/environments/*/servers,/rebuildindex,/users/*/status

To set a token that takes a list of values, append any new values to the current value of the token in the .properties file. Therefore, to add the URI /myuri/* to conf_security_rbac.restricted.resources, edit the /<inst_root>/apigee/customer/application/management-server.properties file as shown below:

conf_security_rbac.restricted.resources=/environments,/environments/*,/environments/*/virtualhosts,/environments/*/virtualhosts/*,/pods,/environments/*/servers,/rebuildindex,/users/*/status,/myuri/*

Locating a token

In most cases, the tokens you need to set are identified in this guide. However, if you need to determine the token used to override a property, perform a grep in the source folder of the component.

For example, if you know that in a previous release of Edge you set the session.maxAge property and want to know the token value used to set it, then grep for the property in the /<inst_root>/apigee/edge-ui/source directory:

> grep -ri "session.maxAge" /<inst_root>/apigee/edge-ui/source

You should see a result in the form:

/<inst_root>/apigee/edge-ui/source/conf/application.conf:session.maxAge={T}conf_application_session.maxage{/T}

The string between the {T}{/T} tags is the token that you set in the .properties file.

Setting a token that is currently commented out

Some tokens are commented out in the Edge configuration files. If you try to set a token that is commented out, the setting is ignored.

To set a token that is commented out, you use a special syntax, in the form:

conf/file.extension+propertyName=propertyValue

For example, you want to set the property named HTTPClient.proxy.host on the Message Processor. You then grep for the property to determine its token:

> cd /opt/apigee/edge-message-processor
> grep -ri "HTTPClient.proxy.host" *

The grep command returns results in the form that includes the token value. Notice how the property name is commented out, as indicated by the # prefix on the property name:

source/conf/http.properties:#HTTPClient.proxy.host={T}conf_http_HTTPClient.proxy.host{/T}
token/default.properties:conf_http_HTTPClient.proxy.host=
conf/http.properties:#HTTPClient.proxy.host=

To set the property, edit /opt/apigee/customer/application/message-processor.properties to set the property as:

conf/http.properties+HTTPClient.proxy.host=myhost.name.com

Notice how the property name is prefixed by conf/http.properties+, the location and name of the configuration file containing the property followed by "+".

After you restart the Message Processor, examine the file /opt/apigee/edge-message-processor/conf/http.properties:

> cat /opt/apigee/edge-message-processor/conf/http.properties

At the end of the file, you will see the property set, in the form:

conf/http.properties:HTTPClient.proxy.host=yhost.name.com