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:
- Customer
- Installer
- 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:
Component | Component Name | Editable Configuration File |
---|---|---|
Cassandra | apigee-cassandra |
/opt/apigee/customer/application/cassandra.properties |
Apigee SSO | apigee-sso |
/opt/apigee/customer/application/sso.properties |
Management Server | edge-management-server |
/opt/apigee/customer/application/management-server.properties |
Message Processor | edge-message-processor |
/opt/apigee/customer/application/message-processor.properties |
apigee-monit |
apigee-monit |
/opt/apigee/customer/application/monit.properties |
Classic UI (does not affect the new Edge UI) | edge-ui |
/opt/apigee/customer/application/ui.properties |
Edge UI (new Edge UI only; does not affect the Classic UI) | apigee-management-ui |
n/a (use the installation configuration file) |
OpenLDAP | apigee-openldap |
/opt/apigee/customer/application/openldap.properties |
Postgres Server | edge-postgres-server |
/opt/apigee/customer/application/postgres-server.properties |
PostgreSQL Database | apigee-postgresql |
/opt/apigee/customer/application/postgresql.properties |
Qpid Server | edge-qpid-server |
/opt/apigee/customer/application/qpid-server.properties |
Qpidd | apigee-qpidd |
/opt/apigee/customer/application/qpidd.properties |
Router | edge-router |
/opt/apigee/customer/application/router.properties |
Zookeeper | apigee-zookeeper |
/opt/apigee/customer/application/zookeeper.properties |
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:
Owner | Filename or Directory |
---|---|
Installation | /opt/apigee/token |
Component | /opt/apigee/component_name/conf Where component_name identifies the component. Possible values include:
|
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:
- Create a new text file in an editor. The file name must match the list shown in the table above for customer files.
- 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:
- Edit the component's
.properties
file. - 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.
- 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
- (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:
- Edit the
/opt/apigee/customer/application/ui.properties
and make sure the file is owned byapigee:apigee
. - 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!
- 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:
- Create a
router.properties
file, if it does not exist, with the path shown below:/opt/apigee/customer/application/router.properties
- Add the following content to the
router.properties
file to create a newlog_format
configuration with the namerouter_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.
- Restart the Router to apply the new configuration:
apigee-service edge-router restart
- 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
- 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