How to configure Edge

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 (sometimes abbreviated as CwC). Essentially, code with config is a key/value lookup tool based on settings in .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 arranged as follows, with customer settings having the highest priority to override any settings from the installer team or Apigee:

1. Customer
2. Installer
3. Component

Determine the current value of a token

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

/opt/apigee/apigee-service/bin/apigee-service component_name configure -search token

Where component_name is the name of the component, and token is the token to inspect.

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

The following example checks the current value of the conf_http_HTTPRequest.line.limit token for the Router:

/opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_http_HTTPRequest.line.limit

You should see output that looks like the following:

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

If the token's value starts with a #, it has been commented out and you must use special syntax to change it. For more information, see Set a token that is currently commented out.

If you do not know the entire name of the token, use a tool such as grep to search by the property name or key word. For more information, see Locate a token.

Properties files

There are editable and non-editable component configuration files. This section describes these files.

Editable component configuration files

The following table lists the Apigee components and the properties files that you can edit to configure those components:

If you want to set a property in one of these component configuration files but it does not exist, you can create it in the location listed above.

In addition, you must ensure that the properties file is owned by the "apigee" user:

chown apigee:apigee /opt/apigee/customer/application/configuration_file.properties

Non-editable component configuration files

In addition to the editable component configuration files, there are also configuration files that you cannot edit.

Informational (non-editable) files include the following:

/opt/apigee/token

/opt/apigee/component_name/conf

Set a token value

You can only modify the .properties files in the /opt/apigee/customer/application directory. Each component has its own .properties file in that directory. For example, router.properties and management-server.properties. For a complete list of properties files, see Location of .properties files.

To create a .properties file:

1. Create a new text file in an editor. The file name must match the list shown in the table above for customer files.
2. Change the owner of the file to "apigee:apigee", as the following example shows:

   chown apigee:apigee /opt/apigee/customer/application/router.properties

   If you changed the user that runs the Edge service from the "apigee" user, use chown to change the ownership to the user which is running the Edge service.

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

To set the value of a token:

1. Edit the component's .properties file.
2. Add or change the value of the token. The following example sets the value of the conf_http_HTTPRequest.line.limit property to "10k":

   conf_http_HTTPRequest.line.limit=10k

   If the token takes multiple values, separate each value with a comma, as the following example shows:

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

   To add a new value to a list such as this, you typically append the new value to the end of the list.

3. Restart the component:

   /opt/apigee/apigee-service/bin/apigee-service component_name restart

   Where component_name is one of the following:

   • apigee-cassandra (Cassandra)
   • apigee-openldap (OpenLDAP)
   • apigee-postgresql (PostgreSQL database)
   • apigee-qpidd (Qpidd)
   • apigee-sso (Edge SSO)
   • apigee-zookeeper (ZooKeeper)
   • edge-management-server (Management Server)
   • edge-management-ui (new Edge UI)
   • edge-message-processor (Message Processor)
   • edge-postgres-server (Postgres Server)
   • edge-qpid-server (Qpid Server)
   • edge-router (Edge Router)
   • edge-ui (Classic UI)

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

   /opt/apigee/apigee-service/bin/apigee-service edge-router restart

4. (Optional) Check that the token value is set to your new value by using the configure -search option. For example:

   /opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_http_HTTPRequest.line.limit

   For more information about configure -search, see Determine the current value of a token.

Locate a token

In most cases, the tokens you need to set are identified in this guide. However, if you need to override the value of an existing token whose full name or location you are unsure of, use grep to search the component's source directory.

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 /opt/apigee/edge-ui/source directory:

grep -ri "session.maxAge" /opt/apigee/edge-ui/source

You should see a result in the following form:

/opt/apigee/component_name/source/conf/application.conf:property_name={T}token_name{/T}

The following example shows the value of the UI's session.maxAge token:

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

The string between the {T}{/T} tags is the name of the token that you can set in the UI's .properties file.

Set 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 in an install or component configuration file, your setting is ignored.

To set the value of a token that is commented out in an Edge configuration file, use special syntax in the following form:

conf/filename+propertyName=propertyValue

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

grep -ri /opt/apigee/edge-message-processor/ -e "HTTPClient.proxy.host"

The grep command returns results that include the token name. Notice how the property name is commented out, as indicated by the # prefix:

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 value of this property, edit /opt/apigee/customer/application/message-processor.properties, but use a special syntax, as the following example shows:

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

In this case, you must prefix the property name with conf/http.properties+. This is 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=myhost.name.com

Configure forward proxy for requests from Send Requests section of Trace UI

This section explains how to configure forward proxy for requests from the Send Requests section of the Trace UI with optional proxy credentials. To configure forward proxy:

1. Edit the /opt/apigee/customer/application/ui.properties and make sure the file is owned by apigee:apigee.
2. Add the following overrides (changing values to your specific proxy configuration):

   conf_application_http.proxyhost=proxy.example.com
   conf_application_http.proxyport=8080
   conf_application_http.proxyuser=apigee
   conf_application_http.proxypassword=Apigee123!

3. Save and restart the classic UI.

Add a custom log format in Apigee Router/Nginx

In some cases, you made need to either change the default Apigee Router/Nginx log format or add variables. To update the default Apigee Router/Nginx log format configuration:

1. Create a router.properties file, if it does not exist, with the path shown below:

   /opt/apigee/customer/application/router.properties

2. Add the following content to the router.properties file to create a new log_format configuration with the name router_new:

   conf_load_balancing_load.balancing.driver.nginx.global.http.parameters.template.extra=log_format router_new 'time_iso8601\\\\thostname\\\\tremote_addr:remote_port\\\\t'\\\\n\\n 'upstream_addr\\\\trequest_time\\\\t-\\\\t-\\\\t'\\\\n\\n 'status\\\\tupstream_status\\\\trequest_length\\\\t'\\\\n\\n 'body_bytes_sent\\\\t'\\\\n\\n 'request\\\\tupstream_http_x_apigee_message_id\\\\t'\\\\n\\n 'http_user_agent\\\\thost\\thostname-pid-connection-connection_requests\\\\tmy_nginx_var_xff\\t'\\\\n\\n 'upstream_http_x_apigee_fault_flag\\\\tupstream_http_x_apigee_fault_source\\\\tupstream_http_x_apigee_fault_code\\\\t'\\\\n\\n 'upstream_http_x_apigee_fault_policy\\tupstream_http_x_apigee_fault_flow\\tupstream_http_x_apigee_fault_revision\\t'\\\\n\\n 'upstream_http_x_apigee_dp_color\\\\tmy_x_apigee_target_latency\\\\t'\\\\n\\n 'upstream_http_x_apigee_proxy\\\\tupstream_http_x_apigee_proxy_basepath\\\\t'\\\\n\\n 'self_region\\\\tself_pod\\\\tself_color\\\\tssl_protocol\\\\tssl_client_verify\\\\tssl_session_id\\\\tssl_session_reused\\\\tupstream_pod\\\\tupstream_region';\\\\n\\n\n
   conf_load_balancing_load.balancing.driver.nginx.access.log={conf_load_balancing_load.balancing.driver.nginx.log.dir}/{org}~{env}.{port}_access_log router_new

   Update the variables in the above commands as appropriate. You can find the default configuration values for log_format in the file below:

   /opt/apigee/edge-router/conf/load_balancing.properties

   A list of Nginx variables is displayed at http://nginx.org/en/docs/varindex.html.

3. Restart the Router to apply the new configuration:

   apigee-service edge-router restart

4. Check whether the new log_format configuration (router_new) has been added to the file /opt/nginx/conf.d/0-default.conf:

       
   cat /opt/nginx/conf.d/0-default.conf | grep router_new -A 10

5. Send some API requests to an API proxy and verify the new log format in the file

   /opt/apigee/var/log/edge-router/nginx/${org}~${env}.${port}_access_log file