URL forwarding (URLFWD) records – NS1 Help Center

URL forwarding (or URL redirection) is a technique used to make a single web page available via multiple URLs. With NS1, you can configure URL forwarding (HTTP redirects or masking) between zones by creating URLFWD records with one or more answers — one answer for each redirect configuration related to that domain.

Each answer within a URLFWD record includes five configuration fields:

"From" (source) path (e.g., /foo)
Target (destination) URL (e.g., http://foo.example.com)
Forwarding type (masking, permanent, or temporary)
Path forwarding mode (all, capture, or none)
Query forwarding (enabled or disabled)

In the portal, you can view existing URLFWD records within the list of records associated with the zone, or by clicking the "URL forwards" tab in the zone details.

Warning

Currently, URL forwarding records do not support answering requests via HTTPS (SSL/TLS termination).

About path forwarding modes

For each answer (that is, for each redirect configuration) within a URLFWD record, you must select a path forwarding mode. The mode you select determines how the NS1 platform will redirect incoming requests — specifically, which part of the incoming request URL path to append (if any) to the target URL — resulting in different expected behaviors.

For example, if you have the following configuration:

Record domain: old.com
Source path: /foo/*
Target URL: new.com/target

Then, incoming requests to old.com/foo/bar are redirected as follows:

Path forwarding mode	Incoming request (what the user searches)	Redirected to (what the user sees)
"All"	old.com/foo/bar	new.com/target/foo/bar
"Capture"	old.com/foo/bar	new.com/target/bar
"None"	old.com/foo/bar	new.com/target

Note

The source path must not end in a slash (/). Otherwise, there will be a double slash in the generated URL.

"All" mode (0)

Warning

When using "all" mode, the source path you specify must contain a variable segment (/*).

If this mode is enabled, the entire URL path of the incoming request URL is appended to the target (destination) URL. Incoming queries must match the source path structure; otherwise, the search will render a "no match" response.

For example, if you configure the following:

Source path = /foo/*
Target URL = new.com/target
Path forwarding mode: All (0)

Then, incoming requests to old.com/foo/bar are redirected to new.com/target/foo/bar. The entire path included in the request is applied to the target URL.

Note that, when using the NS1 API to configure URLFWD records, a value of 0 in the path forwarding field indicates the "all" forwarding mode.

"Capture" mode (1)

Warning

When using "capture" mode, the source path you specify must contain a variable segment (/*).

If this mode is enabled, only the segment of the incoming URL path matching the variable (*) segment of the source path structure is appended to the target URL.

For example, if you configure the following:

Source path = /foo/*
Target URL = new.com/target
Path forwarding mode: Capture (1)

Then, incoming requests to old.com/foo/bar are redirected to new.com/target/bar. Since "/bar" matched the wildcard segment of the source URL, it is appended, whereas all other path segments are not.

Note that, when using the NS1 API to configure URLFWD records, a value of 1 in the path forwarding field indicates the "capture" forwarding mode.

"None" (2)

If this mode is enabled, no part of the of the incoming URL path is appended to the target URL. Incoming searches matching the source path structure are redirected to the target destination as defined. If the incoming URL path does not match the source path structure, then a "no match" response is returned.

For example, if you configure the following:

Source path = /foo/*
Target URL = new.com/target
Path forwarding mode: None (2)

Then, incoming requests to old.com/foo/bar are redirected to new.com/target, whereas requests to old.com/bar render a "no match" response because the request does not follow the source path structure defined in the answer configuration.

Note that, when using the NS1 API to configure URLFWD records, a value of 2 in the path forwarding field indicates the "none" forwarding mode.

Limitations

Support for HTTPS: Currently, NS1 does not support automatic redirection from HTTPS addresses using a URLFWD record. Refer to the table below to see currently supported types of redirections.

From	To	Supported?
http://...	http://...	Yes
http://...	https://...	Yes
https://...	https://...	No
https://...	http://...	No

Create a URLFWD record

You can create a new URL forwarding (URLFWD) record using the NS1 portal or API.

Create a URLFWD record via the portal

Navigate to the zone for which you want to set up a URL redirect. (Go to DNS > Zones, and then click the zone name to view zone details.)
Under the "Records" tab, scroll down and click Add record.

Warning

Adding a URLFWD record to a zone that contains another resource record with the same name may result in unexpected behavior.
In the Record Type drop-down menu, select URLFWD.
In the "name" field, specify the subdomain to apply the URLFWD record, or leave this field blank if you want to create the record at zone apex.
Optionally, specify a time to live (TTL) value in seconds. The default is 3600 seconds. Learn more about Best Practices for TTL configuration.
Under "URL forward options," configure the following fields for each answer within the URLFWD record:
- From - Enter a source path (i.e., subdirectory) with or without a wildcard to the URL, or enter a root "/". This indicates the page the requester will be directed away from upon their query.
- To - Specify the target (destination) URL — including paths (if applicable). This is the page to which the requester will be directed to upon their query.
- Type - Select one of the following types of URL forwarding to use for this redirect configuration:
  - Masking: This type of redirect preserves the redirected domain in the browser's address bar. This lets users see the address they entered, even though the displayed content comes from a different web page.
  - Permanent (301): This type of redirect indicates to search engines that they should remove the old page from their database and replace it with the new target page. This is recommended for SEO.
  - Temporary (302): Less common, this type of redirect indicates that search engines should keep the old domain or page indexed as the redirect is only temporary. While both pages might appear in the search results, a temporary redirect suggests to the search engine that it should prefer the new target page.
- Path forwarding mode - Select a path forwarding mode. There are three path forwarding modes you can use to specify how you want to append to the target path:
  - All - This mode appends the entire incoming path to the target destination.
  - Capture - This mode appends only the part of the incoming path corresponding to the wildcard (*).
  - None - This mode does not append any part of the incoming path.
  Note
  
  Use path forwarding when the domain you are forwarding to has the same structure as the current domain. Refer to "About path forwarding " in the beginning of this article for details.
- Query forwarding - Optionally, select the checkbox next to "Query forwarding" to enable the query string of a URL to be applied directly to the new target URL. The query is indicated by the first question mark ("?"). For example, http://sourceexample.com/page?val=34 where ?val=34 is the query attached to the end of the new target URL. If query forwarding is enabled, this segment of the path is automatically applied to the end of the target destination path. If query forwarding is disabled, the requester is directed to the target destination (without the query appended).
Optionally, to add another redirect for this zone, click Save and add record. Otherwise, click Save record. The new redirect appears in the list of records, as well as within the "URL forwards" tab in the zone details.

Note

It may take up to a few minutes for your changes to propagate.

Create a URLFWD record via API

You can create a new URLFWD record by submitting a PUT request to https://api.nsone.net/v1/zones/{zoneName}/{domain}/URLFWD, specifying the details for each URL redirect as answers in the request body.

curl -X PUT -H "X-NSONE-Key: $NSONE_API_KEY" 
https://api.nsone.net/v1/zones/{zoneName}/{domain}/URLFWD
{
    "zone": "<zoneFQDN>",
    "domain": "<recordDomain>",
    "type": "URLFWD",
    "answers": [
        {
            "answer": [
                "<fromPath>",
                "<targetURL>",
                <forwardingType>,
                <pathForwardingMode>,
                <queryForwarding>
            ]
        }
    ]
}

Table 7. Path parameters

{zoneName}	string	(Required) Unique name of the zone. Typically, this is the same as the zone FQDN unless, during zone creation, you associated the zone with a DNS view or applied a custom zone name.
{domain}	string	(Required) Domain or subdomain to which this record applies. If this is an apex-level record, set this to match the zone FQDN.

Table 8. Request body parameters

zone	string	(Required) Fully qualified domain name (FQDN) of the zone.
domain	string	(Required) Domain or subdomain to which this record applies. If this is an apex-level record, set this to match the zone FQDN.
type	string	(Required) Type of record you are creating. (In this case, `URLFWD`).
answers	array of objects	List of all answer objects within this record.
answer	object	A set of configuration details corresponding to a single answer.
<fromPath>	string	(Required) The first variable in the answer object represents the source path (subdirectory) indicated by the query. In other words, this is the page the requester is directed away from. Optionally, you can include a wildcard (*) in the path, as needed, or enter "/" to specify the root.
<domain>	string	(Required) The second variable in the answer object represents the target (destination) URL, including paths (if applicable), to which to redirect the query.
<forwardingType>	integer	(Required) The third variable in the answer object represents the type of URL redirect you are configuring, either masking (0), permanent (301), or temporary (302). A value of 0 indicates a "masking" redirect. This type of redirect preserves the redirected domain in the browser's address bar so that the user sees the address they entered, even though the content displayed is coming from a different web page. A value of 301 indicates a "permanent" redirect. This type of redirect tells search engines that they should remove the old page from their database and replace it with the new target page. (Recommended for SEO.) A value of 302 indicates a "temporary" redirect. Less common, this type of redirect tells search engines that they should retain the old domain or page indexed as the redirect is only temporary. While both pages might appear in the search results, a temporary redirect suggests to the search engine that it should prefer the new target page.
<pathForwardingMode>	integer	(Required) The fourth value in the answer object represents the path forwarding mode. A value of 0 indicates "all" in which the entire incoming path is appended to the target (destination) URL. A value of 1 indicates "capture" in which only part of the incoming path — that which matches the wildcard (*) segment as defined in the source path structure) — is appended to the target URL. A value of 2 indicates "none" in which no segment of the incoming path is appended to the target URL.
<queryForwarding>	integer	(Required) The fifth value in the answer object indicates query forwarding is enabled or disabled. A value of 0 indicates query forwarding is disabled. A value of 1 indicates query forwarding is enabled.

Example 7. Example: Create a URLFWD record

The example below creates a new URLFWD record with three answers.

{
    "zone": "example.com",
    "domain": "www.example.com",
    "type": "URLFWD",
    "answers": [
        {
            "answer": [
                "/one",
                "http://one.example.com",
                0,
                0,
                0
            ]
        },
        {
            "answer": [
                "/two",
                "http://two.example.com",
                301,
                1,
                1
            ]
        },
        {
            "answer": [
                "/three",
                "http://three.example.com",
                302,
                2,
                0
            ]
        }
    ]
}

Note

For a complete index of NS1 API endpoints, go to ns1.com/api.

Managing URLFWD records

You can view, edit, or delete existing URL forwarding configurations (i.e., URLFWD records) from the "URL forwards" tab in the zone details. This page presents all URL forwarding configurations associated with the selected zone.

You can click the pencil icon to edit a URLFWD record or click the trash can to delete it. You can also add new URLFWD records from this page.

Note

Please allow a few minutes for your changes to propagate.

Articles in this section

Warning

About path forwarding modes

Note

"All" mode (0)

Warning

"Capture" mode (1)

Warning

"None" (2)

Limitations

Create a URLFWD record

Create a URLFWD record via the portal

Warning

Note

Note

Create a URLFWD record via API

Note

Managing URLFWD records

Note

Related articles