Setting up a virtual host

Edge for Private Cloud v. 4.17.05

A virtual host on Edge defines the domains and Edge Router ports on which an API proxy is exposed, and, by extension, the URL that apps use to access an API proxy. A virtual host also defines whether the API proxy is accessed by using the HTTP protocol, or by the encrypted HTTPS protocol.

As part of the Edge onboarding process, you have to create an organization, environment, and virtual host. Edge provides the setup-org command to make this process easier for new users.

When you create the virtual host, you must specify the following information:

  • The name of the virtual host that you use to reference it in your API proxies.
  • The port on the Router for the virtual host. Typically these ports start at 9001 and increment by one for every new virtual host.
  • The host alias of the virtual host. Typically the DNS name of the virtual host.

For example, in a config file passed to the setup-org command, you can specify this information as:

# Specify virtual host information.
VHOST_PORT=9001
VHOST_NAME=default

# If you have a DNS entry for the virtual host.
VHOST_ALIAS=myapis.apigee.net

The Edge Router compares the Host header of the incoming request to the list of available host aliases as part of determining the API proxy that handles the request. When making a request through a virtual host, either specify a domain name that matches the host alias of a virtual host, or specify the IP address of the Router and the Host header containing the host alias.

For example, if you created a virtual host with a host alias of myapis.apigee.net on port 9001, then a cURL request to an API through that virtual host could use one of the following forms:

  • If you have a DNS entry for myapis.apigee.net:

    curl http://myapis.apigee.net:9001/{proxy-base-path}/{resource-path}
  • If you do not have a DNS entry for myapis.apigee.net:

    curl http://<routerIP>:9001/{proxy-base-path}/{resource-path} -H 'Host: myapis.apigee.net'

    In this form, you specify the IP address of the Router, and pass the host alias in the Host header.

    Note: The cURL command, most browsers, and many other utilities automatically append the Host header with the domain as part of the request, so you can actually use a cURL command in the form:

    curl http://<routerIP>:9001/{proxy-base-path}/{resource-path}

Options when you do not have a DNS entry for the virtual host

One option when you do not have a DNS entry is to set the host alias to the IP address of the Router and port of the virtual host, as <routerIP>:port. For example:

VHOST_ALIAS=192.168.1.31:9001

Then you make a curl command in the form below:

curl http://<routerIP>:9001/{proxy-base-path}/{resource-path}

This option is preferred because it works well with the Edge UI.

If you have multiple Routers, add a host alias for each Router, specifying the IP address of each Router and port of the virtual host:

# Specify the IP and port of each router as a space-separated list enclosed in quotes:
# VHOST_ALIAS="192.168.1.31:9001 192.168.1.32:9001"

Alternatively, you can set the host alias to a value, such as temp.hostalias.com. Then, you have to pass the Host header on every request:

curl -v http://<routerIP>:9001/{proxy-base-path}/{resource-path}  -H 'host: temp.hostalias.com'

Or, add the host alias to your /etc/hosts file. For example, add this line to /etc/hosts:

192.168.1.31   temp.hostalias.com

Then you can make a request as if you had a DNS entry:

curl -v http://myapis.apigee.net:9001/{proxy-base-path}/{resource-path}

Using a protected port in a virtual host

If you want to create a virtual host that binds the Router to a protected port, such as port numbers less than 1000, then you have to configure the Router to run as a user with access to those ports. By default, the Router runs as the user "apigee" which does not have access to privileged ports.

To run the Router as a different user:

  1. As root, create the file /opt/apigee/etc/edge-router.d/RUN_USER.sh.
  2. Add the following entry to the file:
    RUN_USER=root
    If you do not want to run the Router as root, specify a user with access to the port.
  3. Save the file.
  4. If you specified a user other than root, change the owner of the file to that user:
    > chown USER:USER /opt/apigee/etc/edge-router.d/RUN_USER.sh
  5. Restart router:
    > /opt/apigee/apigee-service/bin/apigee-service edge-router restart