You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/hybrid/v1.9/base-path-routing). info

In an on-premises installation, you have complete control over virtual hosts. You can create
virtual hosts for any org, in any environments, using TLS or not.

> [!NOTE]
> **Private Cloud:** This document describes how to create a virtual host for an on-premises deployment of Edge. To create a virtual host for a Cloud deployment of Edge, see [Configuring virtual
> hosts for the Cloud](https://docs.apigee.com/api-platform/fundamentals/configuring-virtual-hosts-cloud).

This document describes how to create a simple virtual host. That is, one that does not
support TLS. For more examples, including examples on creating virtual hosts that support TLS,
see [Configuring TLS
access to an API for the Private Cloud](https://docs.apigee.com/api-platform/system-administration/creating-virtual-host).

**Learn more**:

- [About virtual hosts](https://docs.apigee.com/api-platform/fundamentals/virtual-hosts)
- [Configuring virtual hosts](https://docs.apigee.com/api-platform/fundamentals/configuring-virtual-hosts)
- [Configuring TLS](https://docs.apigee.com/api-platform/system-administration/configuring-ssl)
- [Keystores and
  Truststores](https://docs.apigee.com/api-platform/system-administration/keystores-and-truststores)
- [Configuring TLS
  access to an API for the Private Cloud](https://docs.apigee.com/api-platform/system-administration/creating-virtual-host)

## About host aliases

> [!NOTE]
> **Note:** As of Edge for Private Cloud version 4.16.01, you must specify a host alias when creating a virtual host. In releases previous to 4.16.01, the host alias was optional.
>
> Also, the combination of host alias name and port number for the virtual host must be unique
> for all virtual hosts in the Edge installation. If you configure a port number (other than 80 or 443),
> it must be unique and shouldn't have an overlapping port configuration with an
> existing host.

When you create the virtual host, you must specify the host alias of the virtual host.
Typically this is the DNS name of the virtual host.

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]
  > **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 <var translate="no">routerIP</var>:<var translate="no">port</var>. For example:

```
192.168.1.31:9001
```

When 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.

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
```

## About virtual host ports on Edge
for Private Cloud 4.16.01 and later

When creating a virtual host, you specify the Router port used by the virtual host. For
example, port 9001.

For Apigee for Private Cloud releases 4.16.01 and later, by default, the Router runs as the
user "apigee" which does not have access to privileged ports, typically ports 1024 and below. If
you want to create a virtual host that binds the Router to a protected port then you have to
configure the Router to run as a user with access to those ports. See [Setting up a virtual host](https://docs.apigee.com/private-cloud/latest/setting-virtual-host) for more.

## Create virtual hosts

This section describes how to create virtual hosts for Apigee Edge for Private Cloud. Note that to create a new
virtual host, you must be an organization administrator.

You can create virtual hosts for Apigee Edge for Private Cloud using either the API or the Edge UI. These are
described in the following sections.

### Create a virtual host using a browser

This section describes how to create a virtual host by using a browser (Edge UI only).

> [!NOTE]
> **Note:** The virtual host UI is available only when using the [Edge UI](https://docs.apigee.com/private-cloud/v4.19.01/new-edge-experience-private-cloud). It is not available in the Classic Edge UI.

**To create a new virtual host in the Edge UI:**

1. Log in to the Edge management UI.
2. Select **Admin \> Virtual Hosts**.
3. Select the environment from the drop-down list.

   Edge displays a list of virtual hosts for that environment.
4. To create a new virtual host, select **+ Virtual Host** .

   Edge displays the **Create Virtual Host** form.

   You can also click the name of an existing virtual host to edit it.
5. Define your new virtual host. Note that the **Base URL** field must include the protocol (ie, prefix the field's value with "http://" or "https://".)

   Additionally, note that:
   - There is no limit to the number of virtual hosts you can create
   - TLS is optional, and can be version 1.0, 1.1, or 1.2
   - The virtual host's port is configurable
6. Click the **Create** button to save your new virtual host.

### Create a virtual host with the API

To create a virtual host with the API, create an XML object that defines the
virtual host. For example, the following XML object defines a virtual host that uses the HTTP
protocol:

```
<VirtualHost name="myVHost">
   <HostAliases>
     <HostAlias>DNS_name_or_IP:port</HostAlias>
   </HostAliases>
   <Interfaces/>
   <Port>9005</Port>
</VirtualHost>
```

> [!NOTE]
> **Note:** As of Edge for Private Cloud version 4.16.01, you must specify a host alias when creating a virtual host. In releases previous to 4.16.01, the host alias was optional. For more on setting the host alias, see [Configuring TLS access to an API
> for the Private Cloud](https://docs.apigee.com/api-platform/system-administration/creating-virtual-host).

Notice that the virtual host contains a `name` property. You use the value of the
`name` property to configure an API proxy to use the virtual host.

You can then access an API proxy through this virtual host by making a request to:

    http://routerIP:port/proxy-base-path/resource-path
    https://routerIP:port/proxy-base-path/resource-path

Where:

- `http` or `https`: If the virtual host is configured to support TLS, use HTTPS. If the virtual host does not support TLS, use HTTP.
- <var translate="no">routerIP</var>:<var translate="no">port</var> is the IP address and port number of the virtual host.
- <var translate="no">proxy-base-path</var> and <var translate="no">resource-path</var> are defined when you create the API proxy.

Typically, you do not publish your APIs to customers with an IP address and port number.
Instead, you define a DNS entry for the Router and port. For example:

```
http://api.myCompany.com/proxy-base-path/resource-path
https://api.myCompany.com/proxy-base-path/resource-path
```

If you define the DNS entry, then you must create a *host alias* for the virtual host
that matches the domain name of the DNS entry. The host alias must match the string that the
client passes in the `Host` header.
From the example above, you would specify a host alias of `api.myCompany.com`.

```
<VirtualHost name="myVHost">
    <HostAliases>
        <HostAlias>api.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9005</Port>
</VirtualHost>
```

To create a virtual host that uses the HTTP protocol, perform the following:

1. Create the virtual host by using the [Create a
   Virtual Host](https://docs.apigee.com/management/apis/post/organizations/{org_name}/environments/{env_name}/virtualhosts) API, where <var translate="no">ms-IP</var> is the IP address or domain name of the Management Server node:  

   ```
   $ curl -X POST -H "Content-Type:application/xml" \
   http://ms-IP:8080/v1/o/org_name/environments/env_name/virtualhosts \
   -d '<VirtualHost name="newVHost">
       <HostAliases>
         <HostAlias>api.myCompany.com</HostAlias>
       </HostAliases>
       <Interfaces/>
       <Port>9005</Port>
     </VirtualHost>' \
   -u sysAdminEmail:password
   ```
2. Create the DNS record for the virtual host that matches the host alias.
3. If you have any existing API proxies, add the virtual host to the `<HTTPConnection>` element in the Proxy Endpoint. The virtual host is added automatically to all new API proxies. See [Configuring an API proxy to use a virtual host](https://docs.apigee.com/api-platform/fundamentals/configuring-virtual-hosts#configuringanapiproxytouseavirtualhost).

   > [!WARNING]
   > **Warning:** All virtual hosts are automatically added to all new API proxies. Therefore, if you create a new API proxy that should not be accessible over a particular virtual host, then you must edit the API proxy to remove that virtual host from its ProxyEndpoint.

## Modifying a virtual host

> [!WARNING]
> **Warning:** Use this procedure to modify the virtual host settings except those that specify the keystore, alias, and truststore. Changing those properties can require a Router restart depending on how you specified them. See [Update a TLS certificate](https://docs.apigee.com/api-platform/system-administration/update-or-replace-ssl-certificate) for more.

> [!NOTE]
> **Note:** If you change the TLS settings of an existing virtual host for **Edge for Private Cloud versions 4.16.01 and 4.16.05 only**, and do not change the port number of the virtual host, then you have to stop the Router and remove any cached configuration files. After removing the files, you can restart the Router.

To modify a virtual host, perform the following:

1. Update the virtual host by using the
   [Update a Virtual Host](https://docs.apigee.com/management/apis/put/organizations/{org_name}/environments/{env_name}/virtualhosts/{virtualhost_name}) API, where `<ms-IP>` is the IP address
   or domain name of the Management Server node. You must specify the complete definition of the
   virtual host in the request body, not just the elements that you want to change. In this
   example, you change the port number of the virtual host from 9008 to 9009:

   ```
   curl -X PUT -H "Content-Type:application/xml" \
     http://ms-IP:8080/v1/o/org_name/environments/env_name/virtualhosts/vhost_name \
     -d '<VirtualHost name="newVHost">
       <HostAliases>
         <HostAlias>api.myCompany.com</HostAlias>
       </HostAliases>
       <Interfaces/>
       <Port>9009</Port>
     </VirtualHost>' \
     -u email:password
   ```
2. **For Edge for Private Cloud versions 4.16.01 and 4.16.05 only** , If you modify an existing virtual host, and you either enable TLS or disable TLS without changing the port number, then:
   1. Stop the Router:

      ```
      /opt/apigee/apigee-service/bin/apigee-service edge-router stop
      ```
   2. Delete any files in `/opt/nginx/conf.d`:

      ```
      rm -f /opt/nginx/conf.d/*
      ```
   3. Start the Router:

      ```
      /opt/apigee/apigee-service/bin/apigee-service edge-router start
      ```
   4. Repeat for all Routers.