---
name: "traffic_layout"
section: "1"
platform: "linux"
package: "trafficserver"
version: "9.2.5+ds-0+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/traffic_layout"
---

# traffic\_layout(1)

Traffic Server sandbox management tool

## NAME

traffic\_layout - Traffic Server sandbox management tool

## SYNOPSIS

**traffic\_layout** SUBCOMMAND \[OPTIONS\]

## ENVIRONMENT

- **TS\_RUNROOT**

  The path to the run root file. It has the same effect as the command line option *--run-root*.

## DESCRIPTION

Document for the **traffic\_layout** about the **runroot**. This feature is for the setup of Traffic Server runroot. It will create a runtime sandbox for any program of Traffic Server to run under. For details about runroot for programs, please refer to **developer-guide/layout/runroot.en**.

## USAGE

First we need to create a runroot. It can be created simply by calling command *init*.

```
traffic_layout init --path /path/to/runroot
```

A runroot will be created in **/path/to/runroot**, available for other programs to use. If the path is not specified, the current working directory will be used.

- **For example, to run traffic\_manager, using the runroot, there are several ways:**

  - 1\.

    **/path/to/runroot/bin/traffic\_manager**

  - 2\.

    **traffic\_manager --run-root=/path/to/runroot**

  - 3\.

    **traffic\_manager --run-root=/path/to/runroot/runroot.yaml**

  - 4\.

    Set *TS\_RUNROOT* to **/path/to/runroot** and run **traffic\_manager**

  - 5\.

    Run **traffic\_manager** with **/path/to/runroot** as current working directory

**NOTE:**

if none of the above is found as runroot, runroot will not be used and the program will fall back to the default.

## SUBCOMMANDS

### init

Use the current working directory or the specific path to create runroot. The path can be absolute or relative.

- **workflow:**

  - 1\.

    Create a sandbox directory for programs to run under.

  - 2\.

    Copy and symlink build time directories and files to the sandbox, allowing users to modify freely.

  - 3\.

    Emit a YAML file that defines layout structure for other programs to use (relative path).

Example:

```
traffic_layout init (--path /path/to/sandbox/) (--force) (--absolute) (--copy-style=[HARD/SOFT/FULL]) (--layout=special_layout.yml)
```

For the **--layout=\[\<YAML file\>\]** option, a custom layout can be used to construct a runroot. Below is an example of customized yaml file (custom.yml) to construct.

```
prefix: ./runroot
exec_prefix: ./runroot
bindir: ./runroot/custom_bin
sbindir: ./runroot/custom_sbin
sysconfdir: ./runroot/custom_sysconf
datadir: ./runroot/custom_data
includedir: ./runroot/custom_include
libdir: ./runroot/custom_lib
libexecdir: ./runroot/custom_libexec
localstatedir: ./runroot/custom_localstate
runtimedir: ./runroot/custom_runtime
logdir: ./runroot/custom_log
cachedir: ./runroot/custom_cache
```

If **traffic\_layout init --layout="custom.yml"** is executed, a runroot following the format above will be created.

**NOTE:**

*storage.config* does not use the cachedir value, but makes its relatives paths relative to the base prefix. So please update the directory for cache in **storage.config** according to the customized runroot.

### remove

- **Find the sandbox to remove in following order:**

  - 1\.

    specified in --path as absolute or relative.

  - 2\.

    current working directory.

  - 3\.

    installed directory.

Example:

```
traffic_layout remove (--path /path/to/sandbox/) (--force)
```

### verify

Verify the permission of the sandbox. The permission issues can be fixed with **--fix** option. **--with-user** option can be used to verify the permission of the runroot for specific user.

Example:

```
traffic_layout verify (--path /path/to/sandbox/) (--fix) (--with-user root)
```

**WARNING:**

If a custom layout is used and system files are included in some directories, **--fix** option might potentially have unexpected behaviors. For example, if sysconfdir is defined as **/etc** instead of **/etc/trafficserver** in **runroot.yaml**, **--fix** may perform permission changes on the system configuration files. With normally created runroot with default layout, there is no such issue since Traffic Server related files are filtered.

## OPTIONS

- **--run-root=\[\<path\>\]**

  Use the run root file at *path*.

- **-V, --version**

  Print version information and exit.

- **-h, --help**

  Print usage information and exit.

- **-p, --path**

  Specify the path of runroot for commands (init, remove, verify).

### init

- **-f, --force**

  Force init will create sandbox even if the directory is not empty.

- **-a, --absolute**

  Put directories in the YAML file in the form of absolute paths when creating.

- **-c, --copy-style \[HARD/SOFT/FULL\]**

  Specify the way of copying executables when creating runroot. HARD means hard link. SOFT means symlink. FULL means full copy.

- **-l, --layout \[\<YAML file\>\]**

  Use specific layout (providing YAML file) to create runroot.

### remove

- **\`-f\`, \`--force\`**

  Force remove will remove the directory even if it has no YAML file.

### verify

- **-x, --fix**

  Fix the permission issues verify found. **--fix** requires root privilege (sudo).

- **-w, --with-user**

  Verify runroot with certain user. The value can be passed in as the username or **#** followed by uid.

## COPYRIGHT

2026, dev@trafficserver.apache.org