---
title: "Setup"
manual: "Redirects"
version: "main"
permalink: "https://docs.typo3.org/permalink/typo3/cms-redirects:setup@main"
source: "Setup/Index.rst"
rendered: "2026-09-18T12:21:34+00:00"
---

# Setup {#setup}

The redirects extension requires no extra configuration once it is installed.
However, it is recommended to familiarize yourself with
the settings and commands outlined in this page. Depending on your site and how
editing is handled, changes in the configuration and regular maintenance may be
required.

## Site configuration {#site-configuration}

The core comes with the following site settings for redirects which can be
configured per site.

### Configuration via backend module {#configuration-via-backend-module}

The redirect settings can be configured in the backend via
**Site Management > Settings**.

### Configuration via YAML files {#configuration-via-yaml-files}

#### Sites using site sets (TYPO3 v13+) {#sites-using-site-sets-typo3-v13}

For sites using site sets, add the settings to
`config/sites/<site>/settings.yaml`:

```yaml
redirects.autoCreateRedirects: false
redirects.autoUpdateSlugs: true
redirects.redirectTTL: 0
redirects.httpStatusCode: 307
```

Alternatively, you can define these settings in your site package at
`mysitepackage/Configuration/Sets/mysiteset/settings.yaml` to provide
defaults for all sites using this site set.

#### Legacy site configuration (TYPO3 v12 and earlier) {#legacy-site-configuration-typo3-v12-and-earlier}

In legacy installations without site sets, add the settings to
`config/sites/<site>/config.yaml`:

```yaml
settings:
  redirects:
    autoUpdateSlugs: true
    autoCreateRedirects: true
    redirectTTL: 0
    httpStatusCode: 307
```

> [!TIP]
> **Hint**
>
> In older installations, the file is found in
> `typo3conf/sites/<site>/config.yaml`.

### Available settings {#available-settings}

The following settings apply to **automatically created redirects**.
TYPO3 comes with working defaults. It is not necessary to configure these
settings if you use the defaults.

-   ****autoUpdateSlugs****

    Automatically update slugs of all sub pages (default: `true`)

-   ****autoCreateRedirects****

    Automatically create redirects for pages with a new slug (works only in
    LIVE workspace) (default: `true`)

-   ****redirectTTL****

    Time To Live in days for redirect records to be created - `0` disables
    TTL, no expiration (default: `0`)

-   ****httpStatusCode****

    HTTP status code for automatically created redirects, see
    [MDN: HTTP Redirections](https://developer.mozilla.org/en-US/docs/Web/HTTP/Redirections#Temporary_redirections)
    (default: `307`)

The `httpStatusCode` does not affect the default status code for manually created
redirects. This can be adjusted via TCA
`$GLOBALS['TCA']['sys_redirect']['columns']['target_statuscode']['config']['default']`.

<!-- TODO: no Markdown rendering for "versionchanged" -->

Since TYPO3 v12.1, automatically created redirect records are stored on the
configured root page ID of the site. Previously, they were initially stored
on the top root page or later on the changed page.

> [!NOTE]
> **See also**
>
> The `settings` in the site configuration are generally explained in
> "TYPO3 Explained" > [Site settings](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/SiteHandling/SiteSettings.html#sitehandling-settings).

## Console commands {#console-commands}

As for commands in general, it is possible to execute them via the command
line or via the TYPO3 scheduler in the backend.
Please see the general information about this in "TYPO3 Explained" >
[Console commands (CLI)](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/CommandControllers/Index.html#symfony-console-commands-cli).

We explain executing the commands from the command line here, it is recommended
to automate regular execution, e.g. via cron.

### redirects:cleanup {#redirects-cleanup}

The CLI command `redirects:cleanup` can be used to periodically cleanup existing
redirects under given conditions.

Use `-h` to see all options:

**Composer-based installation**

```bash
vendor/bin/typo3 redirects:cleanup -h
```

**Legacy installation**

```bash
typo3/sysext/core/bin/typo3 redirects:cleanup -h
```

**Example 1:** Remove all redirects with less than 50 hits **and** older than 30
days.

**Composer-based installation**

```bash
vendor/bin/typo3 redirects:cleanup -c 50 -a 30
```

**Legacy installation**

```bash
typo3/sysext/core/bin/typo3 redirects:cleanup -c 50 -a 30
```

> [!TIP]
> **Hint**
>
> The `-c` option does nothing if the
> [hitcounter feature toggle](https://docs.typo3.org/permalink/typo3/cms-redirects:hit-counter@main) is not enabled. Be careful
> when using the `-c` (= `--hitCount`) option. It is advised to combine it with
> `-a`, otherwise this will also cleanup redirects which were just created and
> did not have the possibility to accumulate any hits.

**Example 2:** Clean all redirects for domains foo.com and bar.com older than 90 days
and with hit counter less than 100 which start with the source path `/foo/bar`
and have a status code of 302 or 303.

**Composer-based installation**

```bash
vendor/bin/typo3 redirects:cleanup --domain foo.com --domain bar.com \
--age 90 --hitCount 100 --path "/foo/bar%" --statusCode 302 --statusCode 303
```

**Legacy installation**

```bash
typo3/sysext/core/bin/typo3 redirects:cleanup redirects:cleanup --domain foo.com --domain bar.com \
--age 90 --hitCount 100 --path "/foo/bar%" --statusCode 302 --statusCode 303
```

### redirects:checkintegrity {#redirects-checkintegrity}

The checkintegrity command checks existing redirects for conflicts. A typical
conflict may be a [redirect loop](https://docs.typo3.org/permalink/typo3/cms-redirects:redirect-loop@main). In this case the source
and target point to the same page or the redirect loop affects a number of
redirects, each redirecting to the next and looping back to the first, e.g.
`/a => b, /b => /a`.

> [!WARNING]
> Currently, there are known problems where the checkintegrity command
> may report false positives. This can happen if additional routing enhancers
> / decorators are in place.

Example usage to check all sites:

**Composer-based installation**

```bash
vendor/bin/typo3 redirects:checkintegrity
```

**Legacy installation**

```bash
typo3/sysext/core/bin/typo3 redirects:checkintegrity
```

Check only the site mysite:

**Composer-based installation**

```bash
vendor/bin/typo3 redirects:checkintegrity mysite
```

**Legacy installation**

```bash
typo3/sysext/core/bin/typo3 redirects:checkintegrity mysite
```

This will output one line per redirect conflict. The output may look like
this:

```none
Redirect (Host: *, Path: /test-1) conflicts with http://mysite/test-1
```

You can now search for the affected redirects in the redirects module, e.g.
by filtering with *Source Path* `/test-1`.

## Configure editor permission {#editor-permission}

By default, editors (without admin privileges) cannot access redirects directly and they cannot
revert automatic redirects. This can be problematic, because the notification
with the option to revert redirects and the notification that they were reverted
appears regardless, even if an editor does not have access and the redirects
are not reverted.

In order to make **reverting redirects** possible for non-admin backend users,
configure this in the backend group **Access Lists** tab:

-   Activate **Redirect \[sys_redirect\]** in **Tables (listing)**
-   Activate **Redirect \[sys_redirect\]** in **Tables (modify)**

In order to give editors full access to the **redirects module**, give them
access to the `sys_redirect` table as outlined above and configure this in
the backend group **Access Lists** tab:

-   Activate **Link Management > Redirects \[redirects\]** in
    **Modules**.

> [!WARNING]
> It is recommended to only give trusted and experienced backend users access
> to the redirects module because they will have access to all redirects for
> the entire installation and may unintentionally wreak havoc on the site.
>
> Especially problematic can be redirect loops because they result in
> broken pages, but these can be detected, using [redirects:checkintegrity](https://docs.typo3.org/permalink/typo3/cms-redirects:redirects-checkintegrity@main).

By default the fields *Source Domain*, *Source Path* and *Target* are enabled,
the rest are excluded fields, which must be enabled for the respective backend user
group in the **Access Lists** tab > **Allowed excludefields** \>
**Redirect**.

![](../Images/RedirectAllowedExcludefields.png)

## Hit counter {#hit-counter}

The hit counter can be activated via
[Feature Toggle](https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/FeatureToggleApi/Index.html#feature-toggles), either in the backend in
**Settings** \> **Feature Toggles** \>
**Redirects: hit count** or in the
configuration file `system/settings.php` or
`system/additional.php`.

```php
'SYS' => [
    'features' => [
        'redirects.hitCount' => true
    ],
],
```

This feature toggle is disabled by default, because it comes with a small performance
impact that requires additional SQL `UPDATE` queries.

Every time a page is accessed the hit counter will be incremented. Based on the
hit counter, a delete policy for unnecessary redirects can be defined.

Visit the [redirects:cleanup](https://docs.typo3.org/permalink/typo3/cms-redirects:redirects-cleanup@main) with the option
`-c` for more information.

## System reports {#system-reports}

The redirect conflicts will also be shown in the system report, available
via **Reports** \> **Status Report** in the TYPO3 backend.

It is required to run `redirects:checkintegrity` regularly, so that the results
can be displayed in the report.
The information is stored in the registry (`sys_registry` table in the
database).

![](../Images/SystemReportConflicts.png)

In case [redirects:checkintegrity](https://docs.typo3.org/permalink/typo3/cms-redirects:redirects-checkintegrity@main) was not run
within the last 24 hours an additional informational status will appear in the
report:

> [!WARNING]
> **Attention**
>
> List of conflicting redirects may not be up to date!
> Regularly run the console command `redirects:checkintegrity`.

This can be configured in the extension configuration with these 2 settings:

-   [showCheckIntegrityInfoInReports](https://docs.typo3.org/permalink/typo3/cms-redirects:extconf-showcheckintegrityinfoinreports@main)
-   [showCheckIntegrityInfoInReportsSeconds](https://docs.typo3.org/permalink/typo3/cms-redirects:extconf-showcheckintegrityinfoinreportsseconds@main)

## Extension configuration {#extconf}

**Reports**

-   **Show information in reports if checkintegrity was not run.**

    -   *Field:* showCheckIntegrityInfoInReports

    Show informational status in the reports if redirects:checkintegrity was
    not run within the last 24 hours, or rather the number of seconds indicated
    in the setting
    [showCheckIntegrityInfoInReportsSeconds](https://docs.typo3.org/permalink/typo3/cms-redirects:extconf-showcheckintegrityinfoinreportsseconds@main).

-   **Number of seconds to consider last checkintegrity report.**

    -   *Field:* showCheckIntegrityInfoInReportsSeconds
    -   *Default:* 86400 (is 24 hours in seconds)

    Number of seconds which must pass until the informational message is shown
    about checkintegrity in the reports.